@iseoane/agent-depot 0.2.0

package/skills/doctor-md-skill/references/skill-improvements.md

@@ -0,0 +1,32 @@
+# Skill improvement guidelines
+
+## Method
+
+1. Cluster the findings by root cause, across scorers and classifications, after attribution.
+2. Prioritize clusters by frequency times severity.
+3. Verify each finding against the current repository and the agent's configuration before proposing any improvements. Drop what does not verify.
+4. You are editing another agent's instructions. Keep those edits small and general. Before editing, state the intended behavioral rule and owning surface in one sentence, then make the smallest change that expresses it.
+5. Prefer **replacing** existing guidance over **appending** another paragraph.
+
+## When to propose changes
+
+Do not propose changes by default. Proceed only when a concrete instruction is missing or wrong and amending it would have prevented the scored failure. Ask: would a competent agent with the current instructions still be expected to fail this way? If yes, there is a gap. If no, defer.
+
+File only when all of these are true:
+
+- The failure is caused by a missing, wrong, or underspecified instruction on a concrete surface: the owning actor's configuration, a skill, or in-repo guidance.
+- You can name that owning surface and the one reusable rule it should have stated.
+- If that rule had been present and followed, the scored failure would not have happened.
+- The same gap appears in more than one source run, or is severe enough that a single occurrence still proves a missing contract.
+
+Do not file when:
+
+- The existing instruction already required the correct behavior and the model ignored it
+- The failure is model variance: same prompt, same tools, different choice
+- The only available edit is restating, hedging, or adding examples from these runs
+- The real fix is product, infra, scorer, or code outside instruction surfaces
+
+When nothing clears this bar, open no change and say, per finding, why not — that is a success. A speculative change is worse than none.
+
+
+

package/skills/doctor-md-skill/references/supported-harnesses.md

@@ -0,0 +1,44 @@
+# Supported harnesses
+
+This file is the single source of truth for harness support in `doctor-md-skill`. Reference it instead of repeating harness lists in `SKILL.md`.
+
+## Startup gate
+
+| Harness | Collector ID | Local conversation source |
+| --- | --- | --- |
+| Claude Code | `claude` | Project-history JSONL |
+| Codex | `codex` | Rollout JSONL |
+| Pi | `pi` | Pi agent JSONL (`~/.pi/agent/sessions`) |
+| Grok Build | `grok` | Grok Build chat_history JSONL (`~/.grok/sessions`) |
+| ZCode | `zcode` | ZCode model-io rollout (`~/.zcode/cli/rollout`) |
+
+At startup, identify the harness executing the skill from the runtime context. Do not infer it from conversation files found on disk.
+
+If the executing harness is not listed above, or cannot be identified confidently, stop before creating a report directory or reading conversation history. Tell the user:
+
+> doctor-md-skill currently supports Claude Code, Codex, Pi, Grok Build, and ZCode. This run appears to be using an unsupported harness, so no conversations were read.
+
+## Collector source selection
+
+- `--harness auto` scans every locally available supported source and is the default.
+- `--harness all` also requests every supported source.
+- `--harness <collector-id>` restricts collection to one source from the table.
+- A report containing one source uses its collector ID in `inventory.json`; a report containing multiple sources uses `mixed`.
+
+Harness-specific source overrides:
+
+- `--claude-home PATH` — nonstandard Claude Code configuration directory.
+- `--codex-home PATH` — nonstandard Codex home.
+- `--pi-home PATH` — nonstandard Pi agent home (default `~/.pi/agent`).
+- `--grok-home PATH` — nonstandard Grok Build home (default `~/.grok`).
+- `--zcode-home PATH` — nonstandard ZCode home (default `~/.zcode`).
+
+## Skill locations
+
+Project skills are discovered from:
+
+- `.agents/skills`
+- `.claude/skills`
+- `.codex/skills`
+
+Global skills are discovered from the corresponding directories under the user's home and configured harness homes when `--include-global-skills` is set: `~/.claude/skills`, `~/.agents/skills`, `~/.codex/skills`, Pi's skill directory under its agent home (default `~/.pi/agent/skills`), Grok Build's `~/.grok/skills`, and ZCode's `~/.zcode/skills`.

package/skills/doctor-md-skill/scorers/code-quality.md

@@ -0,0 +1,41 @@
+---
+name: Code Quality
+description: "Whether the code, tests, and comments the agent produced are well-designed and consistent with the target repo's conventions."
+labels:
+  - value: "approve"
+    description: "The agent produced well-designed, correct code that is consistent with repo conventions, adequately tested, and clean of smells; a senior reviewer would approve it outright, with at most trivial nits."
+    score: 1
+  - value: "block"
+    description: "The agent produced code with at least one defect a reviewer would insist on fixing before merge: a correctness or concurrency bug, a missed edge case, an inconsistent pattern, weak or missing tests, or mixed-in artifacts that do not belong."
+    score: 0.2
+  - value: "insufficient_evidence"
+    description: "The transcript shows no code diff, or too little of one to judge."
+    score: 0.5
+---
+**Rubric**
+
+This scorer applies to conversations where the agent produced code changes. Evaluate the actual code artifact — the edits themselves, not the process used to produce them. Judge it the way a careful senior reviewer would review the same pull request, using the target repo's own established conventions as the standard. The verdict is binary: `approve` means that reviewer would merge the change as-is, with at most trivial nits; if they would insist on a fix before merging — one real defect is enough — the verdict is `block`. If the condensed transcript doesn't show enough of the change to judge, the verdict is `insufficient_evidence` and the session is excluded from aggregation. The bullets below are common quality dimensions, not an exhaustive checklist — judge any other way the artifact falls short of what a careful senior engineer would ship.
+
+Assess:
+
+- **Design.** The shape of the change fits the codebase; it isn't premature abstraction, scope creep, or a change that belongs somewhere else (a library, a config value, a separate service).
+- **Correctness.** The change does what it claims, including edge cases (nil/empty inputs, boundaries) and concurrency safety (races, unsafe shared state, spawned work that outlives request-scoped values).
+- **Complexity.** No function, type, or expression is doing more than it needs to; no speculative genericity or indirection added for a need that doesn't exist yet.
+- **Repo conventions.** Follows the same idioms as similar code in the same package or module — error handling, type placement, naming schemes, and any other established pattern visible in the surrounding code. An unexplained deviation from a clear local pattern is a defect even if the new code works.
+- **Code smells.** Magic numbers or strings without a named constant, copy-paste that should be a shared function, commented-out code, vague or stale TODOs, workarounds that patch a symptom instead of the root cause, silently swallowed errors, deep nesting that early returns would flatten.
+- **Tests.** Present for the change, and actually verify the behavior they claim to (a broken implementation would fail them) rather than asserting trivia or mocking away the logic under test; cover the error and edge paths, not just the happy path; not so tightly coupled to internals that unrelated changes would break them.
+- **Naming.** Every new identifier communicates what it represents, at a length that's unambiguous without being noisy.
+- **Comments.** Explain why, not what; a doc comment on an exported symbol describes its purpose and constraints without narrating its implementation; no comment describes an edit, a refactor, or a prior state of the code rather than its current behavior.
+- **Diff hygiene.** The change contains only the edits that are intended to be committed — no temporary or transient text, scratch scripts, debug prints, or other verification scaffolding left alongside it.
+- **Documentation.** READMEs, guides, or API docs are updated in the same change when the change affects how the software is built, tested, or used.
+- **Corrections.** A defect the user pointed out mid-conversation counts against the artifact regardless of whether it was ultimately fixed; needing an external correction at all is a negative signal, not just a defect left unresolved.
+
+Out of scope: how directly the agent worked (scored under Efficiency), and whether it followed instructions or skills. Judge the artifact on its own merits.
+
+**Reason**
+
+One to three sentences citing the specific file, pattern, or defect that drove the grade. Name what would have caught it: a lint rule, a repo convention the agent should have searched for, a test case, or a skill. For `insufficient_evidence`, say what you couldn't see — for example, no diff was produced, or the diff wasn't in the transcript.
+
+**Quote**
+
+Alongside the reason, record a `quote`: a verbatim excerpt copied character-for-character from the transcript you were shown, proving the defect (or the clean pattern, for `approve`) is actually there. Copy it, do not paraphrase it, do not tidy its punctuation or whitespace, do not translate it, and do not stitch together two separate passages into one string. The quote is checked mechanically against the transcript text after this step — an unverifiable quote gets the whole finding discarded from aggregation, however accurate the reason sounds. For `insufficient_evidence`, leave `quote` empty; there is nothing in the transcript to cite.

package/skills/doctor-md-skill/scorers/efficiency.md

@@ -0,0 +1,38 @@
+---
+name: Efficiency
+description: "Whether the agent worked directly toward its result, or wasted effort on redundant steps, avoidable rework, or unnecessary back-and-forth."
+labels:
+  - value: "highly_efficient"
+    description: "The agent took a direct path: nothing re-read or re-run, independent steps batched, no work redone."
+    score: 1
+  - value: "mostly_efficient"
+    description: "The agent slipped once or twice: a duplicated read, an early retry, or a small correction — with no knock-on cost."
+    score: 0.8
+  - value: "mostly_inefficient"
+    description: "The agent wasted effort repeatedly, or caused a round of rework an earlier check would have prevented."
+    score: 0.4
+  - value: "highly_inefficient"
+    description: "The agent's waste dominated the run: the same defect reworked across cycles, repeated user correction, or extended flailing / looping."
+    score: 0.2
+---
+**Rubric**
+
+You are scoring one condensed transcript of a local coding-agent conversation. Evaluate the full cost of reaching the result: the steps the agent took, rework it caused, and human attention it consumed. Score against what a competent engineer with the same tools would have needed, not against what was achievable with only what the agent happened to have. A mistake that looks unavoidable in context still counts if better tooling, a skill, or a check would have prevented it — name that cause in the reason. The bullets below are common sources of waste, not an exhaustive checklist — judge any other way the run cost more than it should have.
+
+Assess:
+
+- **Rework from mistakes.** Work redone because the agent got it wrong the first time: a test or build failure a local check would have caught, edits to the wrong file, a misread requirement later reverted.
+- **Cost to the human.** Repeated correction or steering from the user is the most expensive waste. A question asked up front is cheap; the same question asked after building the wrong thing is not.
+- **Information gathering.** Re-reading, re-running, or re-searching for something already found; reading a large file end to end when a targeted search would answer it.
+- **Routine-step overhead.** A roundabout way of doing something that's a standard, repeated part of this agent's job — more steps, more calls, or a broader operation than the step needs — when a more direct path was available. Weight this beyond its one-run cost: the same avoidable overhead recurs on every future conversation until a skill or rule fixes the pattern.
+- **Batching.** Independent reads, searches, or workstreams run serially across turns instead of together.
+- **Flailing.** Retrying a failing approach unchanged, or guessing when reading the code or docs would have settled it. An abandoned path only counts against the agent when the information to avoid it was already available.
+- **Verification timing.** Checks run once, early enough to catch a defect before declaring done, not deferred until after or re-run redundantly.
+
+**Reason**
+
+One to three sentences naming the dominant source of waste with a rough count (three fix-test cycles, four redundant reads, two repeated user corrections), and the likely fixable cause — a missing or weak skill, an ambiguous instruction, a late check. When a skill exists that should have prevented the waste, name the skill.
+
+**Quote**
+
+Alongside the reason, record a `quote`: a verbatim excerpt copied character-for-character from the transcript you were shown, proving the waste (or the clean, direct path, for `highly_efficient`) actually happened — a repeated tool call, the user's own correction, a re-read of something already read. Copy it, do not paraphrase it, do not tidy its punctuation or whitespace, do not translate it, and do not stitch together two separate passages into one string. The quote is checked mechanically against the transcript text after this step — an unverifiable quote gets the whole finding discarded from aggregation, however accurate the reason sounds.