diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..a2585ef --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,8 @@ +{ + "name": "dbga", + "description": "Evidence-first debugging (Python/Go/Node over DAP) plus consolidated language skills and an architect for clean, verified code.", + "owner": { "name": "Nir Adler" }, + "plugins": [ + { "name": "debug-agent", "source": "./plugin" } + ] +} diff --git a/.claude/settings.local.json b/.claude/settings.local.json deleted file mode 100644 index 452a72d..0000000 --- a/.claude/settings.local.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "permissions": { - "allow": [ - "Bash(dir)" - ] - } -} diff --git a/CHANGELOG.md b/CHANGELOG.md index 10ac5c8..f4effad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Fixed + +- Launch-time **exception filters are now replayed to the child session** for + child-delegating adapters (vscode-js-debug). They were only set on the parent + connection, so `--break-on-exception` was silently dropped for Node. + +### Changed + +- **`debug-agent` skill relocated** from `skills/debug-agent/` to + `plugin/skills/debug-agent/` as part of packaging the `debug-agent` Claude + Code plugin. `npx skills add niradler/dbga --skill debug-agent` still resolves + it (via the repo-root `.claude-plugin/marketplace.json`); update any manual + copy path accordingly. + ## [0.1.1] — 2026-05-29 Multi-language release. The debugger is no longer Python-only: the DAP @@ -80,7 +94,7 @@ daemon, with auto-context returned on every stop. (truncated to 200-char strings / 5-item collection previews), full stack (capped at 20 frames), recent output, warnings. No follow-up calls needed. Configurable via `--context-lines`. -- **`debug-agent` skill** (`skills/debug-agent/`) — Claude/agent +- **`debug-agent` skill** (`plugin/skills/debug-agent/`) — Claude/agent skill that drives `dbga` with evidence-first workflow, log monitoring, localization, instrumentation, debugger, VS Code collab, and advanced (hang/deadlock/wolf-fence/concurrency) reference docs. diff --git a/CLAUDE.md b/CLAUDE.md index ac67904..c11ba14 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co `dbga` (distribution) / `debug_agent` (import name) — an evidence-first **Python** debugger CLI built on top of `debugpy`/DAP. The CLI surface is stateless; a per-session background daemon owns the live DAP connection. Every stop returns auto-contextualized JSON (location, source window, locals, full stack, recent output, warnings) so an AI agent can drive a real debugger one command at a time. -Status: alpha. Python-only by design today — `debugpy` and `"type": "python"` are hardcoded in the launch path. +Status: alpha. Multi-language over DAP via the `adapters/` registry: **Python** (debugpy, the most-validated path), **Go** (Delve), and **Node/TypeScript** (vscode-js-debug). Python is the richest surface — `instrument` source probes are Python-centric and the Node multi-process lifecycle is not yet validated (see the `debug-agent` skill's "Honest Limits"). Adding a language means subclassing `adapters.base.Adapter` and registering it. ## Commands @@ -72,6 +72,6 @@ Every CLI command returns a single JSON object on stdout via `core/format.emit_p - **Tear-down is best-effort and idempotent.** `DapSession.release()` is called from `finally`. Tree-killing the adapter is the unconditional fallback after a graceful `disconnect` request. - **The daemon idle-timeout watchdog** (default 1800s) exists so a forgotten session can't linger forever — don't disable it without thinking about cleanup. -## The skill (`skills/debug-agent/`) +## The skill (`plugin/skills/debug-agent/`) -A Claude/agent skill ships in-repo at `skills/debug-agent/`. It documents the evidence-first workflow that the CLI is designed for (`SKILL.md` + `references/*.md`). If you change CLI command shapes or JSON schemas, audit the skill — it has concrete command examples that go stale silently. +A Claude/agent skill ships in-repo at `plugin/skills/debug-agent/` (part of the `debug-agent` Claude Code plugin under `plugin/`). It documents the evidence-first workflow that the CLI is designed for (`SKILL.md` + `references/*.md`). If you change CLI command shapes or JSON schemas, audit the skill — it has concrete command examples that go stale silently. diff --git a/README.md b/README.md index 30e502a..f3e18d3 100644 --- a/README.md +++ b/README.md @@ -143,44 +143,61 @@ they belong next to the code. Add `.debug-agent/` to your `.gitignore`: └── lock # liveness marker ``` -## The `debug-agent` Skill +## The `debug-agent` Claude Code plugin -`skills/debug-agent/` contains a Claude / agent skill that teaches -evidence-first debugging on top of `dbga`. It includes: +`plugin/` is a [Claude Code plugin](https://docs.claude.com/en/docs/claude-code) +that bundles `dbga` with a full design → develop → debug → verify → clean-up +workflow for Python, Go, and Node/TypeScript: -- **`SKILL.md`** — when to trigger, decision tree, mindset -- **`references/workflow.md`** — the evidence-first loop -- **`references/log-monitoring.md`** — using `watch` -- **`references/localization.md`** — `localize` and `diagnose` -- **`references/instrumentation.md`** — reversible probes -- **`references/debugger.md`** — driving `session` -- **`references/vscode-collab.md`** — `--listen` + shared breakpoints -- **`references/advanced.md`** — hang / deadlock / concurrency / wolf-fence +- **Skills** (`/debug-agent:*`): `debug-agent` (the evidence-first `dbga` driver), + plus `python`, `go`, `node` development skills that route to language-specific + references on demand. +- **Agents** (`/agents`): `architect` (orchestrator) and `python-expert`, + `go-expert`, `node-expert`. +- **Command:** `/debug-agent:setup` — optional one-shot `dbga` installer. -### Install the skill +Full plugin docs: [`plugin/README.md`](plugin/README.md). -The recommended path is [`npx skills`](https://github.com/vercel-labs/skills), -the open agent-skills installer. It reads `SKILL.md` straight from the GitHub -repo and drops it into `~/.claude/skills/` (or your agent host's equivalent): +### Install — full plugin (recommended) ```sh -# Install just this skill -npx skills add niradler/dbga --skill debug-agent +claude plugin marketplace add niradler/dbga +/plugin install debug-agent@dbga +/debug-agent:setup # optional: installs the dbga CLI +``` + +### Install — a single skill + +The [`skills`](https://github.com/vercel-labs/skills) CLI installs any one skill +standalone (skills only — agents/commands come with the full plugin). Resolution +is automatic via the repo-root marketplace manifest; no `--full-depth` needed: -# Or preview what's available first -npx skills add niradler/dbga --list +```sh +npx skills add niradler/dbga --skill python # or: go | node | debug-agent +npx skills add niradler/dbga --list # preview what's available ``` -Manual install also works: +Manual install of just the debugger skill also works: ```sh # Linux / macOS -cp -r skills/debug-agent ~/.claude/skills/ +cp -r plugin/skills/debug-agent ~/.claude/skills/ # Windows PowerShell -Copy-Item -Recurse skills/debug-agent $env:USERPROFILE\.claude\skills\ +Copy-Item -Recurse plugin/skills/debug-agent $env:USERPROFILE\.claude\skills\ ``` +### What the `debug-agent` skill covers + +- **`SKILL.md`** — when to trigger, decision tree, mindset +- **`references/workflow.md`** — the evidence-first loop +- **`references/log-monitoring.md`** — using `watch` +- **`references/localization.md`** — `localize` and `diagnose` +- **`references/instrumentation.md`** — reversible probes +- **`references/debugger.md`** — driving `session` +- **`references/vscode-collab.md`** — `--listen` + shared breakpoints +- **`references/advanced.md`** — hang / deadlock / concurrency / wolf-fence + ## Development ```sh diff --git a/docs/superpowers/evals/RESULTS.md b/docs/superpowers/evals/RESULTS.md new file mode 100644 index 0000000..7d1234c --- /dev/null +++ b/docs/superpowers/evals/RESULTS.md @@ -0,0 +1,58 @@ +# Trigger-separation eval — results (2026-05-29) + +Lean dev-aid eval per the plugin spec (a goal, not a ship gate). Harness: +skill-creator `scripts/run_eval.py`, which installs a skill's `description` as a +temp command and runs `claude -p ` to see whether the model invokes it. + +Query pool: `trigger-queries.json` — 16 queries, 4 per skill intent +(python / go / node / debug-agent). For each skill the same pool is relabeled +`should_trigger = (intent == skill)`, so the other 12 act as cross-skill +near-miss negatives. + +## Results (WSL/Linux, skills CLI harness, runs-per-query 1–3) + +| Skill | Passed | Negatives (no mis-trigger) | Positives (auto-trigger ≥0.5) | +| --- | --- | --- | --- | +| debug-agent | 12/16 | 12/12 ✅ | ~1/4 | +| python | 12/16 | 12/12 ✅ | ~0/4 | +| go | 13/16 | 12/12 ✅ | ~1/4 | +| node | 12/16 | 12/12 ✅ | ~0/4 | + +- **Cross-skill separation (the property that matters for a 4-skill plugin): + excellent and uniform.** Every skill stays quiet on the other three skills' + intents (12/12 negatives each). No mis-trigger observed anywhere. +- **Positive auto-trigger rate is uniformly low — a harness ceiling, not a + prompt defect.** Discriminating test: re-running `debug-agent` with a + deliberately punchy, imperative description ("Use this skill whenever…", + explicit trigger keywords, "Always use before guessing") produced **no lift** + (still ~1/4). A description-quality problem would vary by skill and respond to + a stronger trigger; instead the rate is flat across all skills and unresponsive + to description strength. The cause is methodology: `run_eval.py` injects each + skill as a `.claude/commands/` entry and measures whether one-shot `claude -p` + auto-invokes it — and one-shot non-interactive runs tend to just do the task + rather than auto-invoke a command. Real plugin-installed skills trigger via a + different path. + +## Why `run_loop` auto-optimization was not run + +`run_loop` maximizes positive trigger rate. The discriminating test shows that +rate is capped by the harness, not the description, so optimization would chase +a biased proxy and risk overfitting descriptions that are already triggers-only, +keyword-rich, independently reviewed, and behaviorally validated (see the +buggy-script baseline-vs-with-skill test). Decision: keep the reviewed +descriptions; rely on the clean separation result. + +## Windows note (original blocker) + +On native Windows the positive axis was entirely unmeasurable: `run_eval.py` +polls the `claude -p` subprocess **pipe** with `select.select()`, and Windows +`select` accepts only sockets → `WinError 10038`. WSL/Linux fixes this (Linux +`select` works on pipe fds). Rerun under WSL with: + +```sh +PYTHONPATH= uv run --no-project --with pyyaml python run_eval.py \ + --eval-set .json --skill-path plugin/skills/ --runs-per-query 3 +``` + +(`--no-project` is required so `uv` does not try to repair the Windows-format +`.venv` over the `/mnt/c` mount.) diff --git a/docs/superpowers/evals/trigger-queries.json b/docs/superpowers/evals/trigger-queries.json new file mode 100644 index 0000000..402ee4a --- /dev/null +++ b/docs/superpowers/evals/trigger-queries.json @@ -0,0 +1,21 @@ +[ + { "query": "Add type hints to this module and get it passing mypy --strict", "intent": "python" }, + { "query": "Write a Pythonic async FastAPI endpoint that fetches rows from Postgres", "intent": "python" }, + { "query": "My .py script raises AttributeError on a None value, refactor it cleanly", "intent": "python" }, + { "query": "Make this asyncio code stop blocking the event loop", "intent": "python" }, + + { "query": "I have a data race detected by go test -race in my worker pool", "intent": "go" }, + { "query": "Wrap these errors with %w and check them with errors.Is in my Go service", "intent": "go" }, + { "query": "My goroutines deadlock: all goroutines are asleep - deadlock", "intent": "go" }, + { "query": "Use functional options for this Go struct constructor", "intent": "go" }, + + { "query": "Fix this TypeScript TS2345 error, the argument is not assignable", "intent": "node" }, + { "query": "My Express handler has an unhandled promise rejection, make it robust", "intent": "node" }, + { "query": "Write an advanced conditional type that unwraps a Promise in TypeScript", "intent": "node" }, + { "query": "Cannot read properties of undefined in my Node EventEmitter code", "intent": "node" }, + + { "query": "My program crashes with a traceback and I want to triage it to the failing frame", "intent": "debug-agent" }, + { "query": "Pause my script at a breakpoint and inspect the live value of a variable", "intent": "debug-agent" }, + { "query": "The process hangs and I need to see live runtime state, not guess from source", "intent": "debug-agent" }, + { "query": "Set a breakpoint and step to find where this value first goes wrong", "intent": "debug-agent" } +] diff --git a/docs/superpowers/plans/2026-05-29-debug-agent-plugin.md b/docs/superpowers/plans/2026-05-29-debug-agent-plugin.md new file mode 100644 index 0000000..52f4008 --- /dev/null +++ b/docs/superpowers/plans/2026-05-29-debug-agent-plugin.md @@ -0,0 +1,101 @@ +# debug-agent Plugin — Implementation Plan (high-level) + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. +> **This is a borrow-and-refine plan, not from-scratch.** Tasks state the goal, the source material to pull, refinement directives, and acceptance criteria. **The executing subagent decides the specific edits** — what to copy, cut, merge, and reword — within those boundaries. Do not expect prescribed line-by-line code. + +**Goal:** Ship a Claude Code plugin `debug-agent` bundling the existing `dbga` debugger skill + 3 consolidated language skills (Python/Go/Node) + 4 agents (architect + 3 experts), installable as a full plugin and as single skills via `npx skills`. + +**Architecture:** Plugin lives at `plugin/` with `.claude-plugin/marketplace.json` at repo root. Canonical skills under `plugin/skills/`; language-invariant content in `skills/_shared/`; agents in `plugin/agents/`. Content is merged from wshobson/agents + VoltAgent (both MIT) and refined with our Evidence-First + clean-code principles. + +**Tech stack:** Markdown SKILL.md + agent definitions; `dbga` (Python CLI); skill-creator eval harness; `npx skills` CLI; `claude plugin validate`. + +**Spec:** `docs/superpowers/specs/2026-05-29-debug-agent-plugin-design.md` — read it before starting; it holds the principles, layout, and decisions every task must honor. + +--- + +## Phase 0 — De-risk first (do before anything else) + +### Task 0: Verify `npx skills` resolves the planned layout +**Why first:** the whole canonical-skills-under-`plugin/skills/` decision rests on this. The `skills` CLI does NOT scan arbitrary depth by default. +- Create a throwaway `plugin/skills/probe/SKILL.md` and run `npx skills add --skill probe`. +- **Acceptance:** resolves cleanly. If it does NOT, switch to declaring skills in the manifest (or `--full-depth`) and record the chosen mechanism in the spec's Decisions section before proceeding. Delete the probe. + +--- + +## Phase A — Plugin skeleton (main thread, sequential) + +### Task 1: Scaffold plugin + manifests +**Files:** `plugin/.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` (repo root), `plugin/README.md`, `plugin/LICENSE`, `plugin/THIRD_PARTY_NOTICES.md`. +- Use the manifest sketches in the spec verbatim as the starting point. +- README documents BOTH install paths + the name glossary (`dbga` marketplace / `debug-agent` plugin / `debug_agent` import). +- `THIRD_PARTY_NOTICES.md`: placeholder structure now; subagents fill upstream MIT text + SHA per file they vendor. +- **Acceptance:** `claude plugin validate ./plugin` passes; `claude --plugin-dir ./plugin` loads with no errors. + +### Task 2: Move the `debug-agent` skill into the plugin +**Scope:** move `skills/debug-agent/` → `plugin/skills/debug-agent/` (keep its references intact). Update **all 5** references: `CLAUDE.md`, `CHANGELOG.md`, `README.md` (×3). +- Verify `git check-ignore -v plugin/.claude-plugin/plugin.json` does NOT match `.gitignore`'s `.claude/`. +- **Acceptance:** repo test suite still green (`uv run pytest -m "not e2e"`); the moved skill loads under the plugin; existing `npx skills add … --skill debug-agent` documented against the new path. +- **Exempt** this SKILL.md from the <500-word rule — do not rewrite it. + +### Task 3: Author `skills/_shared/` +**Files:** `plugin/skills/_shared/{clean-code,evidence-first,dependency-hygiene}.md`. +- Language-invariant only. clean-code = self-explaining, no-comments-unless-asked (mirror `code-simplifier` philosophy). evidence-first = the validation/debug discipline + the canonical Evidence-First block (single source of truth). dependency-hygiene = audit-then-**suggest** (mark mutating commands as suggest-only, never auto-run). +- **Acceptance:** the three files exist, are concise, and are the only home for this content (language skills will cross-reference them by name). + +### Task 4: Author the `architect` agent +**Files:** `plugin/agents/architect.md` (model: opus). +- Orchestration loop per spec; wired as opt-in main-thread agent (NOT forced via settings.json `agent` key). Allowed to dispatch the experts with per-call model override. Concise: checklist + when-to-delegate, defers detail to skills. +- **Acceptance:** appears in `/agents`; running `claude --agent debug-agent:architect` lets it dispatch an expert. + +### Task 5: `/debug-agent:setup` command + Task 6: `references/agent-teams.md` + Task 7: fix CLAUDE.md +- T5: `plugin/commands/setup.md` — optional installer (uv → pipx → pip fallback), prints `dbga --version`, notes missing Go/Node toolchains. **Acceptance:** `/debug-agent:setup` installs and confirms version. +- T6: `plugin/references/agent-teams.md` — document the experimental teams path (Windows = in-process). **Acceptance:** file present, accurate. +- T7: update repo `CLAUDE.md` "Python-only by design today" to the merged multi-language reality, matching the skill's Honest Limits. **Acceptance:** line no longer contradicts the shipped Go/Node support. + +--- + +## Phase B — Per-language (one subagent each, parallel, non-overlapping paths) + +> Dispatch 3 subagents — Python, Go, Node. Each owns ONLY `plugin/skills//**` and `plugin/agents/-expert.md`. **Each subagent figures out exactly what to borrow and how to refine it** within the directives below. + +### Task 8 / 9 / 10: Build `` skill + `-expert` agent +**Sources to pull (MIT):** +- Python: wshobson `python-development` skills (design-patterns, anti-patterns, code-style, error-handling, async, project-structure) + agent `python-pro`; VoltAgent `python-pro` depth. +- Go: wshobson `systems-programming/go-concurrency-patterns` + agent `golang-pro`; VoltAgent `golang-pro`. +- Node: wshobson `javascript-typescript` skills (modern-js, ts-advanced-types, nodejs-backend, js-testing) + agents `typescript-pro`/`javascript-pro`; VoltAgent `typescript-pro` (primary) + `javascript-pro` (JS-fallback section only). + +**Directives:** +- Write `plugin/skills//SKILL.md` as a **slim index (<500 words)** routing to `references/` (language-specific deltas only — see spec layout). Cross-reference `skills/_shared/*` and `debug-agent` **by name**; do NOT copy their content. +- Write language-specific reference files (design-patterns, concurrency/async, types where relevant, errors-structure, debugging recipes with `dbga`). +- Write `plugin/agents/-expert.md` (model: sonnet) — merge VoltAgent depth + wshobson structure, dedup, inject the Evidence-First block, point at its skill. Concise; no restating reference content. +- `description` = triggers only ("Use when…"), no workflow summary, keyword-rich. +- Add upstream MIT notice + SHA to `THIRD_PARTY_NOTICES.md` for files substantially copied. +- Draft `plugin/skills//evals/evals.json` (2–3 realistic prompts). +- **Acceptance:** skill loads as `/debug-agent:`; `wc -w SKILL.md` < 500; expert in `/agents`; references present; evals.json present; no duplication of `_shared` content. + +--- + +## Phase C — Eval + final verification + +### Task 11: Behavioral scenarios (all 4 skills) +- Run the 3 subagent scenarios from the spec (e2e architect→debug→fix→verify; correct-reference retrieval; no-comments-under-pressure) via the skill-creator baseline-vs-with-skill pattern, through a POSIX shell, `generate_review.py --static`. +- **Acceptance:** with-skill beats baseline on the no-comments + evidence-first assertions; gaps fed back into the skills. + +### Task 12: One shared description-trigger optimization +- Single ~20-query set (negatives = cross-skill near-misses python/go/node/debug-agent); run `run_loop`; apply each `best_description`. +- **Acceptance:** the four skills fire on their own intent and stay quiet on the others'. + +### Task 13: Full benchmark for `debug-agent` + `python` only +- aggregate_benchmark → review. Go/Node spot-checked, not full-looped. +- **Acceptance:** positive with-skill delta recorded (goal, not hard gate). + +### Task 14: Release verification +- `claude plugin validate ./plugin`; `--plugin-dir` load; `/help` lists `/debug-agent:*`; `/agents` lists architect + 3 experts; `npx skills add --skill python|go|node|debug-agent` each install standalone; e2e architect loop on a known-buggy script. +- **Acceptance:** all pass; tag `0.1.0`. + +--- + +## Notes +- Frequent commits per task on `feat/claude-plugin`. +- No AI attribution in commits/PRs (per user rules). +- Each Phase-B subagent works in isolated paths to avoid write conflicts; the main thread merges `THIRD_PARTY_NOTICES.md` additions if they touch the same file. diff --git a/docs/superpowers/specs/2026-05-29-debug-agent-plugin-design.md b/docs/superpowers/specs/2026-05-29-debug-agent-plugin-design.md new file mode 100644 index 0000000..0672f76 --- /dev/null +++ b/docs/superpowers/specs/2026-05-29-debug-agent-plugin-design.md @@ -0,0 +1,392 @@ +# Design: `debug-agent` Claude Code Plugin + +Date: 2026-05-29 +Status: Final — ready for implementation plan +Owner: Nir + +## Goal + +Package the `dbga` evidence-first debugger plus a consolidated set of +language skills and specialist agents as a distributable **Claude Code +plugin**, giving a complete **design → develop → debug deeply → verify → +clean up** workflow for Python, Go, and Node. + +Two install paths must both work cleanly: + +1. **Full plugin** via marketplace — + `claude plugin marketplace add niradler/dbga` then + `/plugin install debug-agent@dbga`. +2. **Single skill** via the `skills` CLI — + `npx skills add niradler/dbga --skill python` (or `go`, `node`, + `debug-agent`). + +## Final shape + +**4 agents** and **4 skills** — one consolidated skill + one expert per +language, an `architect` to orchestrate, and the debugger skill. + +### Agents (`agents/*.md`) + +| Agent | Model | Scope | +| --- | --- | --- | +| `architect` | **opus** | Language-agnostic. Owns high-level design, decomposition, cross-cutting decisions, and the evidence-first orchestration loop: gather runtime evidence → delegate language work to the matching expert → verify against real flows. Delegates; rarely writes code itself. | +| `python-expert` | sonnet (architect may override to opus for hard tasks) | Full Python specialist. Drives the `python` + `debug-agent` skills. | +| `go-expert` | sonnet (overridable) | Full Go specialist. Drives the `go` + `debug-agent` skills. | +| `node-expert` | sonnet (overridable) | TypeScript-focused (small JS-fallback section). Drives the `node` + `debug-agent` skills. | + +There is no separate `code-reviewer` agent: clean-code review is a +cross-cutting responsibility every agent carries (see Working Principles) and +is backed by each skill's `clean-code` reference. + +### Skills (`skills/*/SKILL.md`) + +| Skill | Role | +| --- | --- | +| `python` | Main Python development skill. SKILL.md routes to many reference files (progressive disclosure). | +| `go` | Main Go development skill + references. | +| `node` | Main Node/TypeScript development skill + references. | +| `debug-agent` | Existing evidence-first `dbga` driver (Python/Go/Node over DAP). Moved into the plugin. | + +Each skill is **self-contained** → any one installs cleanly on its own via +`npx skills`. Agents are plugin-only (the `skills` CLI installs skills, not +agents) — expected and documented. + +## Source material & licensing + +We **combine and learn from both** MIT-licensed sources — the goal is the +best result, not fidelity to any one repo: + +- **wshobson/agents** (MIT) — has both agents and skills. Supplies the + per-topic skill content (design-patterns, code-style, error-handling, async, + anti-patterns, concurrency) and lean specialist agents. +- **VoltAgent/awesome-claude-code-subagents** (MIT) — agents only, but deep + (e.g. `python-pro` ≈ 3,800 words: operational checklists, type-system + mastery, async, testing methodology, security, collaboration protocol). + +Combination rules: + +1. **Each language skill** consolidates the relevant wshobson skills as + **language-specific reference files**, enriched with the matching deep + sections harvested from VoltAgent's agents. Language-**invariant** content + (clean-code/no-comments, evidence-first discipline, dependency-hygiene + discipline) is authored **once** in `skills/_shared/` and cross-referenced + by name — never triple-copied across python/go/node. +2. **Each expert agent** merges the VoltAgent + wshobson versions of that + language (VoltAgent depth + wshobson structure), deduplicated, then points + at its skill + the `debug-agent` skill. +3. The `architect` agent is **authored fresh** (no single upstream + equivalent), distilling the cross-cutting orchestration + working + principles below. +4. Preserve upstream LICENSE/attribution; record the source commit SHA of each + vendored file. + +## Working principles (embedded in every agent + each skill's SKILL.md) + +These are the non-negotiables the whole plugin enforces: + +1. **Evidence and validation first.** Decisions are made by validating against + **real use flows run against the code** — not by reasoning about source. + Use logs, debugger breakpoints (`dbga`), and common practices to observe + what actually happens. Never declare a fix done until correct behavior is + **observed** at the point the bug occurred. +2. **Debug with the toolkit, don't guess.** On a crash/hang/wrong-output, + reach for the `debug-agent` skill and `dbga` (diagnose, live sessions, + `eval`, instrument) before sprinkling prints or guessing fixes. +3. **Proactive dependency hygiene.** On new install/setup and when touching + dependencies, push to latest and audit proactively, then suggest bumps: + - Node: `npm outdated`, `npm audit`, `npm install @latest`. + - Python: `uv lock --upgrade` / `uv pip install -U`, `pip-audit`. + - Go: `go list -u -m all`, `go get -u ./...`, `govulncheck ./...`. +4. **Clean, self-explaining code** (mirrors the official `code-simplifier`): + - Readable and **explicit over compact**; clarity beats brevity. + - **Never add code comments unless explicitly asked.** Code should explain + itself through clear names and structure. Remove comments that restate + obvious code. + - Avoid nested ternaries; prefer if/else or switch for multiple conditions. + - Reduce nesting and redundancy; consolidate related logic. + - Preserve functionality; don't over-simplify or strip helpful + abstractions. +5. **Deliver clean, working, verified code — always.** The loop is design → + implement → run real flows → debug with evidence → simplify → verify. +6. **Token economy.** These files are read by an agent, not a human. Slim, + to-the-point, minimum words while keeping what's vital. Authoring + constraints below enforce this. + +## Authoring constraints (slim, agent-facing — from writing-skills) + +Every skill and agent in this plugin follows: + +- **SKILL.md is the slim index, not the manual.** Target < 500 words; route to + `references/*.md` via progressive disclosure. Heavy/per-topic detail lives in + references, loaded only when needed. +- **Descriptions are triggers only.** Third person, start with "Use when…", + list symptoms/contexts. **No workflow summary** (a summarized description + makes the agent skip the body). +- **Names:** lowercase, hyphenated, active (`python`, `go`, `node`, + `debug-agent`; reference files like `error-handling`, `clean-code`). +- **Keyword coverage** for discovery (errors, symptoms, tool/command names). +- **Cross-reference by name**, not `@path` (no force-loading). Reference the + matching expert agent and `debug-agent` skill where relevant. +- **One excellent example per pattern**, not many; no multi-language dilution. +- **Agents are concise too** — operational checklist + when-to-delegate, detail + deferred to the skills they drive rather than restated inline. + +A short version of principles 1–2 is injected as a standard **Evidence-First +Debugging** block in each agent/skill body: + +```markdown +## Evidence-First Debugging (debug-agent toolkit) + +You have `dbga` — an evidence-first debugger for Python/Go/Node over DAP — +and the `debug-agent` skill. When code crashes, hangs, produces wrong output, +or you need live runtime state, DO NOT guess from source. Gather evidence: + +- `dbga diagnose -- ` → triage a crash to the deepest user frame +- `dbga session start --break-at file:line --