netcoredbg-mcp

Imported from thebtf/netcoredbg-mcp (AGENTS.md). Install upstream with npx skills add thebtf/netcoredbg-mcp. Copyright stays with the author.

AGENTS.md — Project Agent Instructions

🧠 BASE PRINCIPLE

You are a skeptical expert. Your default mode is to verify, cross-check, and reason carefully.

• Never assume the user is right — or that you are
• Treat every claim as a hypothesis to be tested
• Prioritize accuracy over confidence, clarity over speed, evidence over assumption
• Before acting: "What could go wrong? What am I missing?"

🛑 LANGUAGE

• Communication with user: [YOUR LANGUAGE]
• Everything else: ENGLISH (code, docs, commits, PRs)

⛔ CRITICAL RULES

NON-NEGOTIABLE. Violation = Revert.

⛔ WORKAROUNDS FORBIDDEN

If solution contains "simple", "quick", "temporary", "workaround" — STOP and rethink.

1. STOP — No workarounds
2. ANALYZE — Find root cause
3. PROPOSE — Correct solution
4. ASK — If unsure

🚀 Git & RELEASE WORKFLOW

NON-NEGOTIABLE. Always follow.

Release process:

1. When a bounded spec, PRD, ADR, or active run contract explicitly includes a planned release, its integration scope reaches main, and no dependent slice in the same integration wave remains active, start release preparation automatically. If release intent is absent or explicitly out of scope, do not expand the run into a release.
2. Create a release-prep branch (for example, work/release-v1.0.1-prep).
3. Update version, changelog, release notes, and other release-owned surfaces; build and install the release candidate; then run the primary UXDD consumer-mode release gate through the public CLI/MCP entry point. Every user journey claimed by the release must reach PRODUCT_WORKS; PARTIALLY_WORKS and BROKEN block release regardless of unit-test status.
4. Run the remaining local pre-PR protocol gates in docs/RELEASE-PROTOCOL.md and record their evidence in the release report.
5. Commit, push, and create a release PR.
6. Run independent MCP PR review plus required CI and test-protocol checks; resolve all blocking findings.
7. After final review correction, run the pre-merge exact-head SonarQube gate on CANDIDATE_SHA. Fix every finding in code, rerun affected review/checks, and rescan until every finding is FIXED_IN_CURRENT_HEAD. Merge only after primary UXDD, review, this candidate receipt, and required checks are clean.
8. Fast-forward local main to the merged origin/main target, then run a fresh post-merge SonarQube scan against that exact SHA. The tag target must equal the post-merge receipt SHA; a mismatch, scan finding, or unavailable Sonar input blocks tag creation until repaired and rescanned.
9. Create and push the annotated PATCH/MINOR tag only after the completed integration scope is on main, no dependent slice in the same integration wave remains active, the post-merge receipt, and every other pre-publication gate pass; then run post-publication verification per docs/RELEASE-PROTOCOL.md.

Recovery (immutable tags): A pushed release tag is immutable and collision-safe. If post-publication verification fails but the tagged commit and release artifacts are correct, repair or retry only the failed publication step for the same vX.Y.Z, then re-run post-publication verification. If code, metadata, or artifacts must change, create and merge a hotfix PR that bumps to a new patch version, rerun every mandatory pre-publication gate in docs/RELEASE-PROTOCOL.md, restart from step 9, and publish a new annotated tag on the corrected main commit. Never move, delete, or reuse an already-pushed release tag.

🧾 AGENT-GENERATED WORKTREE TRACES

The repository owner does not manually edit this checkout during agent work. Unexpected tracked-file dirtiness is therefore agent/tooling residue until proven otherwise.

Before source edits, commits, release work, or tests that may regenerate tracked files:

1. Run git status --short --branch.
2. For every dirty tracked path, capture git diff -- <path>.
3. Classify each path:
   • intended work — belongs to the current task.
   • known generated churn — expected output from a named command/tool.
   • unknown residue — not explained by the active task.
   • blocker — may affect tests, release, branch switching, or verification.
4. Record command, path, diff summary, and classification in .agent/CONTINUITY.md when the residue affects future agents.

Forbidden without explicit user decision:

• git restore, git checkout --, git reset, git clean, stash, or branch deletion against unknown residue.
• Committing generated residue just because the worktree is dirty.
• Building, testing, releasing, or opening a PR from a checkout whose dirty tracked files are unclassified.
• Building, testing, releasing, or opening a PR from a checkout with blocker-classified residue until that residue is resolved, explicitly approved by the user, or isolated away from the work in a clean sibling worktree.

Lockfile rule: uv.lock is a reproducibility artifact. Local uv commands can update the editable package's own version entry without a human source edit. Treat editable-package version churn as tooling residue unless the active task intentionally changes dependency resolution or package version metadata. Do not commit or discard it in an unrelated task without an explicit decision.

Clean implementation rule: If unknown residue exists on main, create a clean sibling worktree (using git worktree) for implementation work and keep the residue documented in the original checkout.

📍 KEY PATHS

🧪 TESTING

Before writing tests, read: .agent/guides/TESTING_GUIDELINES.md

Smoke Test Protocol:

• Current: 87 checks (85 pass, 2 known failures: XPath on WinForms, file dialog)
• Run: NETCOREDBG_PATH="D:/Bin/netcoredbg/netcoredbg.exe" python tests/smoke_test_manual.py
• GUI tests require dotnet build tests/fixtures/SmokeTestApp -c Debug first
• When fixing a bug: add smoke test BEFORE the fix, verify it fails, then fix, verify it passes

Test Scratch Hygiene (NON-NEGOTIABLE — learned 2026-07-01):

• Isolated pytest runs that set UV_PROJECT_ENVIRONMENT=.agent/tmp/uv-<name> create a full throwaway venv (hundreds of MB each). These are NOT auto-removed. Over a multi-CR marathon they silently accumulated 13.3 GB / ~498k files in .agent/tmp before the first cleanup.
• Rule: after an isolated UV_PROJECT_ENVIRONMENT=.agent/tmp/... run, remove that venv dir in the SAME task, OR reuse ONE stable env name across runs instead of a fresh per-CR dir. Do not leave per-CR venvs behind.
• .agent/tmp/ is gitignored scratch: safe to wipe wholesale when idle. On Windows, robocopy <empty-dir> .agent\tmp /MIR /MT:16 clears a large tree in seconds; PowerShell Remove-Item -Recurse on 100k+ small files times out.
• Periodic check: if .agent/tmp exceeds ~1 GB, wipe it during housekeeping.

Reproduction-First Debugging Protocol:

• Behavior bugs MUST be reproduced on a controlled test program, fixture, smoke scenario, or regression test before product-code edits.
• Preferred fixture surfaces: tests/fixtures/SmokeTestApp, tests/fixtures/WpfSmokeApp, tests/fixtures/AvaloniaSmokeApp, and tests/smoke_test_manual.py.
• If the existing fixtures cannot express the reported behavior, extend the fixture first. Do not patch product code around an unmodeled symptom.
• Prove RED on current code, fix the root cause, prove GREEN on the same check, then replay the original user-observable scenario or record an explicit blocker naming the missing capability.
• /nvmd-platform:debug --quick is allowed only for exact file/line errors with a <=2-line non-control-flow fix and no plausible competing hypothesis. The smallest regression test still belongs with the fix.

Coverage Targets: (customize per project)

• Core Domain: 80%
• Critical Paths: 100%

🎯 SKILLS

Skills are provided by the global nvmd-platform plugin and user-scope rules. This project keeps no local skills — DAP protocol details live as versioned reference material in docs/dap-protocol/.

Note: .agent/ (including CONTINUITY.md) is gitignored — paths under it below are local-only and bootstrapped per clone.

🔧 TOOL PREFERENCES

📚 LESSONS LEARNED

File: .agent/LESSONS_LEARNED.md

When to WRITE: Bug pattern, debugging insight, architectural lesson, process improvement.

### YYYY-MM-DD: Short Title
**Problem:** What went wrong
**Root Cause:** Why it happened
**Lesson:** What to do/avoid next time

📓 Continuity Ledger

Maintain a single .agent/CONTINUITY.md (no per-role split).

Format:

# CONTINUITY — netcoredbg-mcp

## Goal (incl. success criteria)
## Constraints/Assumptions
## Key decisions
## State
### Done
### Now
### Next
## Open questions
## Working set

Rules:

• Read at session start, update when state changes
• Keep short: facts only, no transcripts
• Mark uncertainty as UNCONFIRMED

📛 NAMING CONVENTIONS

Branches: work/{type}-{desc} or work/epic{N}-{desc}

Commits: type(scope): description

• Examples: feat(core): add feature, fix(parser): null check

Types: feat, fix, docs, refactor, test, chore