agentme 0.37.0 → 0.37.1

package/.xdrs/agentme/edrs/application/skills/azure-devops-connector/SKILL.md

@@ -8,7 +8,8 @@ description: >
   DevOps.
 metadata:
   author: flaviostutz
-  version: "1.1"
+  version: "1.2.0"
+  updated: 2026-09-21
 ---
 
 ## Overview
@@ -21,6 +22,27 @@ dedicated subcommand. Contains no business logic (per rule 05): it only reads an
 data and normalizes it to the shape consumed by
 [`resolve-pr-comments`](../../../principles/skills/resolve-pr-comments/SKILL.md).
 
+### Inputs
+
+#### Required
+- PR identifier (org/project/repo + number) and operation
+
+#### Optional
+- Thread/comment id (replies, status changes)
+
+### Outputs
+
+#### Contents
+- Normalized thread/comment records; write confirmation
+
+#### Changes
+- PR thread comments or thread status (writes only)
+
+### Halt Conditions
+- `az`/`azure-devops` extension missing or unauthenticated
+- Write operation lacks explicit human confirmation
+- Only a non-`az` HTTP fallback is available
+
 ## Instructions
 
 ### Authentication check
@@ -195,6 +217,18 @@ threads/comments `POST`, then updates thread status via the `PATCH` call.
   organization before relying on it; degrade to the PR's own URL with no anchor when
   uncertain, rather than guessing at a format that might mislead the human.
 
+## Anti-Patterns
+
+- **Mistake:** Trusting a zero exit code from `az rest` as proof a write persisted.
+  **Why it happens:** `az rest` can silently fall back to an anonymous identity and still exit 0.
+  **Instead:** Always pass `--resource ...` explicitly and re-read the thread to confirm.
+- **Mistake:** Falling back to `curl`/web-UI scraping when `az` is missing or unauthenticated.
+  **Why it happens:** The target data often looks read-only, so a workaround feels harmless.
+  **Instead:** Stop at the Authentication check and wait for the human to fix `az`.
+- **Mistake:** Emitting a `"review-summary"` kind or fabricating a `diff_hunk` for Azure DevOps.
+  **Why it happens:** Callers modeled on GitHub's shape expect those fields to exist.
+  **Instead:** Normalize to `"thread-comment"` and leave `diff_hunk` null when absent.
+
 ## References
 
 - [`resolve-pr-comments`](../../../principles/skills/resolve-pr-comments/SKILL.md) -- consumes this connector's normalized output.

package/.xdrs/agentme/edrs/application/skills/azure-devops-connector/SKILL.test.md

@@ -1,6 +1,6 @@
 ---
 skill: azure-devops-connector
-skill-version: "1.0"
+skill-version: "1.2.0"
 ---
 
 ## Test Scenarios

package/.xdrs/agentme/edrs/application/skills/create-golang-project/SKILL.md

@@ -6,7 +6,8 @@ description: >
   asks to create, scaffold, or initialize a new Go project, CLI binary, or Go module.
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.1.0"
+  updated: 2026-09-21
 compatibility: Go 1.21+
 ---
 
@@ -16,6 +17,27 @@ Creates a complete Go project from scratch, following the layout from [agentme-e
 
 Related EDRs: [agentme-edr-102](../../102-golang-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md), [agentme-edr-126](../../126-pragmatic-hexagonal-architecture.md)
 
+### Inputs
+
+#### Required
+- Go module path (e.g. `github.com/<owner>/<project>`)
+
+#### Optional
+- Binary name, description, author, Go version, feature name
+
+### Outputs
+
+#### Contents
+- `go.mod`, `main.go`, Makefile, `.golangci.yml`, `app/<feature>/`, `adapters/cli/`
+
+#### Changes
+- None
+
+### Halt Conditions
+- Module path not specified and not inferable from context
+- Business logic requested inside `main.go` or `adapters/cli/`
+- Unsure whether an `internal/` package is justified
+
 ## Instructions
 
 ### Phase 1: Gather information
@@ -352,3 +374,34 @@ Fix any compile or lint errors before finishing.
 - All development tasks go through `make` targets. The Makefile recipes call `mise exec -- go ...` and related tools directly.
 - Do not create an `internal/` package unless explicitly justified (importability is preferred).
 - If the project is a reusable library, place consumer examples in a sibling `examples/` folder outside the module root and keep them on the public module import path.
+
+## Examples
+
+**Input:** "Create a Go CLI project called `logscan` for parsing log files"
+- Module `github.com/<owner>/logscan`, binary `logscan`, feature package `parse`
+- Creates `main.go`, `Makefile`, `.mise.toml`, `.golangci.yml`, `go.mod`
+- Creates `app/parse/parse.go` plus test, `adapters/cli/parse.go`
+- Verifies with `make setup && make all`
+
+**Input:** "Scaffold a Go module inside an existing monorepo"
+- Uses the workspace module path plus the project subdirectory as the module name
+- Reuses the monorepo's shared Makefile conventions instead of duplicating them
+
+## Edge Cases
+
+- **Existing files** — skip creation; adapt references to the existing structure.
+- **Library instead of CLI** — omit `adapters/cli/` and `main.go`; place consumer examples in a sibling `examples/` folder.
+- **Multiple features from the start** — scaffold each as its own `app/<feature>/` package; do not merge unrelated logic into one package.
+- **Outbound integration needed** — add `adapters/connectors/<resource>/` rather than calling external services from `app/`.
+
+## Anti-Patterns
+
+- **Mistake:** Putting business logic directly in `main.go` or `adapters/cli/`.
+  **Why it happens:** It is the fastest path to a working binary during scaffolding.
+  **Instead:** Keep `main.go`/CLI adapters thin; put logic in `app/<feature>/`.
+- **Mistake:** Using `fmt.Println` for diagnostic or debug output.
+  **Why it happens:** It is the simplest way to print while writing new code.
+  **Instead:** Log with `logrus` at the appropriate level instead.
+- **Mistake:** Creating an `internal/` package by default.
+  **Why it happens:** It feels like a safe default that blocks unwanted external imports.
+  **Instead:** Keep packages importable unless there is an explicit justification.

package/.xdrs/agentme/edrs/application/skills/create-golang-project/SKILL.test.md

@@ -1,6 +1,6 @@
 ---
 skill: create-golang-project
-skill-version: "1.0"
+skill-version: "1.1.0"
 ---
 
 ## Test Scenarios

package/.xdrs/agentme/edrs/application/skills/create-javascript-project/SKILL.md

@@ -7,7 +7,8 @@ description: >
   package, or similar project structure.
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.1.0"
+  updated: 2026-09-21
 compatibility: JavaScript/TypeScript, Node.js 18+
 ---
 
@@ -22,6 +23,26 @@ into `.cache/`, and uses Makefiles as the only entry points. Boilerplate is deri
 
 Related EDRs: [agentme-edr-101](../../101-javascript-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md), [agentme-edr-126](../../126-pragmatic-hexagonal-architecture.md)
 
+### Inputs
+
+#### Required
+- Package name (npm-compatible)
+
+#### Optional
+- Description, author, Node.js version, CLI vs. library
+
+### Outputs
+
+#### Contents
+- Root/`lib`/`examples` Makefiles, `package.json`, `src/`
+
+#### Changes
+- None
+
+### Halt Conditions
+- Package name not specified and not inferable from context
+- Unclear whether the project needs CLI bundling or examples
+
 ## Instructions
 
 ### Phase 1: Gather information
@@ -446,3 +467,15 @@ All `[package-name]` replaced with `retry-client`.
 - **CLI tool** — add `"bin": "dist/main.js"` to `package.json` and create `lib/src/main.ts` as the CLI entry point; add `esbuild` bundle target in `lib/Makefile`
 - **No examples needed** — omit the `examples/` directory; remove the `examples` delegation from root `Makefile`
 - **Binary bundling (Lambda/browser)** — add an esbuild step to `lib/Makefile`: `pnpm exec esbuild src/main.ts --bundle --platform=node --outfile=dist/bundle.js`
+
+## Anti-Patterns
+
+- **Mistake:** Creating `examples/` even when the user said no examples were needed.
+  **Why it happens:** The scaffolding template always includes an `examples/` folder by default.
+  **Instead:** Omit `examples/` and remove its delegation from the root `Makefile`.
+- **Mistake:** Adding a CLI `bin` entry without an `esbuild` bundle target.
+  **Why it happens:** `package.json`'s `bin` field is easy to add but easy to forget bundling for.
+  **Instead:** Always pair a CLI entry point with an `esbuild` bundle target in `lib/Makefile`.
+- **Mistake:** Leaving `[package-name]` placeholders unreplaced in generated files.
+  **Why it happens:** Placeholders are copied from boilerplate across many files at once.
+  **Instead:** Verify every `[package-name]` occurrence was replaced before finishing.

package/.xdrs/agentme/edrs/application/skills/create-javascript-project/SKILL.test.md

@@ -1,6 +1,6 @@
 ---
 skill: create-javascript-project
-skill-version: "1.0"
+skill-version: "1.1.0"
 ---
 
 ## Test Scenarios

package/.xdrs/agentme/edrs/application/skills/create-python-project/SKILL.md

@@ -6,7 +6,8 @@ description: >
   scaffold, or initialize a new Python package, CLI, or similar project structure.
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.1.0"
+  updated: 2026-09-21
 compatibility: Python 3.12+
 ---
 
@@ -20,6 +21,27 @@ organizes internal code following [agentme-edr-126](../../126-pragmatic-hexagona
 
 Related EDRs: [agentme-edr-103](../../103-python-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md), [agentme-edr-126](../../126-pragmatic-hexagonal-architecture.md)
 
+### Inputs
+
+#### Required
+- Package name (Python distribution/import name)
+
+#### Optional
+- Description, author, Python version, entry point, repo URL
+
+### Outputs
+
+#### Contents
+- Root/`lib/` Makefiles, `pyproject.toml`, `src/`, `tests/`, examples
+
+#### Changes
+- None
+
+### Halt Conditions
+- Package name not specified and not inferable from context
+- Framework-specific request conflicts with the baseline layout
+- Unsure whether the spike/experiment lint exemption applies
+
 ## Instructions
 
 ### Phase 1: Gather information
@@ -404,6 +426,18 @@ After creating the files:
 - If an example needs extra dependencies, keep them in that example's `pyproject.toml`; do not move them into `lib/pyproject.toml` unless the library truly needs them.
 - If the user asks for an app with framework-specific needs such as FastAPI or Django, keep this baseline and add the framework config on top instead of replacing it.
 
+## Anti-Patterns
+
+- **Mistake:** Assuming host-installed Python/`uv` instead of pinning versions in `.mise.toml`.
+  **Why it happens:** The host tools appear to work fine during local testing.
+  **Instead:** Always pin the Python and `uv` versions in the root `.mise.toml`.
+- **Mistake:** Moving an example's extra dependencies into `lib/pyproject.toml`.
+  **Why it happens:** One shared dependency list looks simpler than several.
+  **Instead:** Keep example-only dependencies in that example's own `pyproject.toml`.
+- **Mistake:** Skipping examples and linting for any project that feels small.
+  **Why it happens:** "Small project" is treated as sufficient justification on its own.
+  **Instead:** Only skip when the project is under 100 lines AND another XDR explicitly allows it.
+
 ## References
 
 - [agentme-edr-103](../../103-python-project-tooling.md)

package/.xdrs/agentme/edrs/application/skills/create-python-project/SKILL.test.md

@@ -1,6 +1,6 @@
 ---
 skill: create-python-project
-skill-version: "1.0"
+skill-version: "1.1.0"
 ---
 
 ## Test Scenarios

package/.xdrs/agentme/edrs/application/skills/github-connector/SKILL.md

@@ -7,7 +7,8 @@ description: >
   post PR comments, resolve review threads, or check out a PR branch on GitHub.
 metadata:
   author: flaviostutz
-  version: "1.1"
+  version: "1.2.0"
+  updated: 2026-09-21
 ---
 
 ## Overview
@@ -20,6 +21,27 @@ rule 05): it does not decide what a comment means, what action to take, or when
 it only reads and writes data and normalizes it to the shape consumed by
 [`resolve-pr-comments`](../../../principles/skills/resolve-pr-comments/SKILL.md).
 
+### Inputs
+
+#### Required
+- PR identifier (`owner/repo` + number) and operation
+
+#### Optional
+- Comment/thread id (replies, resolution)
+
+### Outputs
+
+#### Contents
+- Normalized comment/thread records; write confirmation
+
+#### Changes
+- PR comments, replies, thread resolution (writes only)
+
+### Halt Conditions
+- `gh` CLI missing or unauthenticated
+- Write operation lacks explicit human confirmation
+- Only a non-`gh` HTTP fallback is available
+
 ## Instructions
 
 ### Authentication check
@@ -177,6 +199,18 @@ thread via the GraphQL mutation using that comment's thread node id.
   `GH_PAGER=cat gh api repos/{owner}/{repo}/issues/{n}/comments`) when running non-
   interactively, which disables `gh`'s pager unconditionally.
 
+## Anti-Patterns
+
+- **Mistake:** Falling back to `curl`/HTML scraping when `gh` is missing or unauthenticated.
+  **Why it happens:** The target data is often technically public, so a workaround feels harmless.
+  **Instead:** Stop at the Authentication check and wait for the human to fix `gh`.
+- **Mistake:** Assuming a numeric REST comment/review id also works for GraphQL mutations.
+  **Why it happens:** Both values look like ordinary identifiers for the same comment.
+  **Instead:** Always resolve the thread's GraphQL node id first via `reviewThreads`.
+- **Mistake:** Posting a write without showing the mandatory confirmation summary.
+  **Why it happens:** The payload already looks correct, so confirmation feels redundant.
+  **Instead:** Always show System/Operation/Fields/Impact and wait for explicit confirmation.
+
 ## References
 
 - [`resolve-pr-comments`](../../../principles/skills/resolve-pr-comments/SKILL.md) -- consumes this connector's normalized output.

package/.xdrs/agentme/edrs/application/skills/github-connector/SKILL.test.md

@@ -1,6 +1,6 @@
 ---
 skill: github-connector
-skill-version: "1.0"
+skill-version: "1.2.0"
 ---
 
 ## Test Scenarios

package/.xdrs/agentme/edrs/application/skills/run-skill-tests/SKILL.md

@@ -6,13 +6,35 @@ description: >
   or validate a skill, or before merging a PR that modifies a skill or its SKILL.test.md.
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.1.0"
+  updated: 2026-09-21
 ---
 
 ## Overview
 
 Loads `SKILL.test.md` from a skill directory, runs each scenario by invoking the target skill with the specified trigger, evaluates every assertion against the output, and produces a structured test report.
 
+### Inputs
+
+#### Required
+- Path to the skill directory to test
+
+#### Optional
+- None
+
+### Outputs
+
+#### Contents
+- Structured PASS/FAIL test report, per scenario and assertion
+
+#### Changes
+- None (read-only; never modifies the skill or test file)
+
+### Halt Conditions
+- Skill path not provided and not inferable from context
+- Skill directory or `SKILL.test.md` not found
+- `SKILL.test.md` has no scenarios
+
 ## Instructions
 
 ### Phase 1: Locate and Validate SKILL.test.md
@@ -111,6 +133,18 @@ A scenario passes only when every one of its assertions passes. The overall outc
 - If the target skill fails to activate (e.g., not registered in VS Code), note this in the report as FAIL with reason "skill could not be activated" and continue to remaining scenarios.
 - If `skill-version` in `SKILL.test.md` does not match `SKILL.md`, emit a WARNING at the top of the report but do not halt.
 
+## Anti-Patterns
+
+- **Mistake:** Modifying the skill or its test file while testing it.
+  **Why it happens:** An obvious bug seen mid-test is tempting to fix right away.
+  **Instead:** Never modify either file; only report the FAIL and evidence.
+- **Mistake:** Treating an INCONCLUSIVE assertion as a pass.
+  **Why it happens:** An ambiguous result can feel close enough to success.
+  **Instead:** Always treat INCONCLUSIVE the same as FAIL, with a reason.
+- **Mistake:** Silently continuing when `skill-version` mismatches `SKILL.md`.
+  **Why it happens:** A version-string mismatch looks cosmetic and unimportant.
+  **Instead:** Emit a visible WARNING at the top of the report.
+
 ## References
 
 - [`agentme-edr-policy-017`](../../../principles/017-skill-testing.md) — Skill testing mandate and SKILL.test.md format specification

package/.xdrs/agentme/edrs/application/skills/run-skill-tests/SKILL.test.md

@@ -1,6 +1,6 @@
 ---
 skill: run-skill-tests
-skill-version: "1.0"
+skill-version: "1.1.0"
 ---
 
 ## Test Scenarios

package/.xdrs/agentme/edrs/application/skills/select-relevant-xdrs/SKILL.md

@@ -7,7 +7,8 @@ description: >
    bootstrap agentme guidance into a repository without manually deciding which records to keep.
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.1.0"
+  updated: 2026-09-21
 compatibility: Node.js 18+
 ---
 
@@ -17,6 +18,27 @@ Installs the full agentme XDR set for a repository through the published CLI, th
 records that clearly do not fit the target project by passing explicit `--exclude` flags during
 extraction.
 
+### Inputs
+
+#### Required
+- Target repository to install/update agentme XDRs into
+
+#### Optional
+- Explicit list of XDRs to keep or exclude
+
+### Outputs
+
+#### Contents
+- Installed `.xdrs/` tree, minus excluded records
+
+#### Changes
+- Existing `.xdrs/` merged/updated in place
+
+### Halt Conditions
+- Package does not expose enough metadata to enumerate shipped XDRs
+- Extraction would overwrite locally customized agent files
+- Candidate exclusion is debatable (keep instead of guessing)
+
 ## Instructions
 
 ### Phase 1: Discover the available extractable artifacts
@@ -131,6 +153,18 @@ Input: "Set up agentme for this repo"
 - If the repository is a spike or intentionally minimal experiment, still prefer the smallest preset
    set of workflow artifacts and avoid adding scaffolding that the project will not use.
 
+## Anti-Patterns
+
+- **Mistake:** Excluding an XDR whenever its fit is merely debatable.
+  **Why it happens:** Fewer records feels like a cleaner, more tailored result.
+  **Instead:** Keep the XDR; exclude only records that clearly do not fit.
+- **Mistake:** Overwriting locally customized agent files during extraction.
+  **Why it happens:** Preset extraction defaults to replacing existing files.
+  **Instead:** Warn the user first and describe the likely merge points.
+- **Mistake:** Failing immediately when the CLI cannot list shipped XDRs directly.
+  **Why it happens:** The direct enumeration path is the expected happy path.
+  **Instead:** Fall back to published package metadata or the README inventory.
+
 ## References
 
 - [agentme README](../../../../../../README.md)

package/.xdrs/agentme/edrs/application/skills/select-relevant-xdrs/SKILL.test.md

@@ -1,6 +1,6 @@
 ---
 skill: select-relevant-xdrs
-skill-version: "1.0"
+skill-version: "1.1.0"
 ---
 
 ## Test Scenarios

package/.xdrs/agentme/edrs/platform/skills/monorepo-setup/SKILL.md

@@ -8,7 +8,8 @@ description: >
   complies with the standard structure.
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.1.0"
+  updated: 2026-09-21
 ---
 
 ## Overview
@@ -20,6 +21,27 @@ test any part of the monorepo with a single, predictable command.
 
 Related EDRs: [agentme-edr-301](../../301-monorepo-structure.md), [agentme-edr-502](../../../governance/502-contributing-guide-requirements.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md)
 
+### Inputs
+
+#### Required
+- Applications and modules to scaffold or extend
+
+#### Optional
+- Primary language(s), tool versions, target directory
+
+### Outputs
+
+#### Contents
+- Root/app/module Makefiles, READMEs, `.mise.toml`, `.gitignore`
+
+#### Changes
+- None
+
+### Halt Conditions
+- Applications/modules not specified and not inferable from context
+- Cross-application dependency requested (ambiguous boundary)
+- Existing README/Makefile found without explicit confirmation
+
 ## Instructions
 
 ### Phase 1: Gather information
@@ -338,3 +360,15 @@ test:
 - **Module with no compilable output (e.g., pure scripts):** Still create the Makefile; `build` can be a no-op (`@true`) but the target must exist.
 - **Language not listed above:** Mirror the pattern — `build` produces an artifact, `lint` runs static analysis, `test` runs tests. Adapt commands to the actual toolchain.
 - **Existing files:** Never overwrite existing `README.md`, `CONTRIBUTING.md`, or `Makefile` files without user confirmation. Diff and propose additions instead.
+
+## Anti-Patterns
+
+- **Mistake:** Letting one application import another application's code directly.
+  **Why it happens:** Reaching across app folders feels faster than publishing a shared library.
+  **Instead:** Refuse the direct import and move the shared code into `shared/libs/`.
+- **Mistake:** Silently overwriting an existing `README.md`, `CONTRIBUTING.md`, or `Makefile`.
+  **Why it happens:** Scaffolding logic assumes a clean, empty target directory.
+  **Instead:** Diff against the existing file and propose additions instead of overwriting.
+- **Mistake:** Skipping the `Makefile` for a module with no compilable output.
+  **Why it happens:** A pure-script module seems to need no build step at all.
+  **Instead:** Still create the Makefile with a no-op `build` target (`@true`) for consistency.

package/.xdrs/agentme/edrs/platform/skills/monorepo-setup/SKILL.test.md

@@ -1,6 +1,6 @@
 ---
 skill: monorepo-setup
-skill-version: "1.0"
+skill-version: "1.1.0"
 ---
 
 ## Test Scenarios

package/.xdrs/agentme/edrs/principles/skills/refine-plan-mode/SKILL.md

@@ -8,7 +8,8 @@ description: >
   the XDRS repository even when not directly exposed in the .agents skills folder.
 metadata:
   author: flaviostutz
-  version: "3.0"
+  version: "3.1.0"
+  updated: 2026-09-21
 ---
 
 ## Overview
@@ -29,6 +30,27 @@ Ensures that every plan is deeply validated through iterative consistency checks
 
 **Artifact rule**: The plan is a single continuously-edited final artifact, not an append-only log. Process detail — Q&A rounds, phase-gate confirmations, todo-list tracking — never enters the deliverable; todos stay in the agent's todo-list tool. When a later phase reverses an earlier decision or section, edit it in place — never leave the superseded content beside the replacement. The final artifact's structure follows the **Final Plan Artifact Template** below.
 
+### Inputs
+
+#### Required
+- Task, feature, or decision to plan
+
+#### Optional
+- Constraints, prior art, related decisions
+
+### Outputs
+
+#### Contents
+- Final Plan Artifact (steps, verification, decisions)
+
+#### Changes
+- None until Phase 7 handoff
+
+### Halt Conditions
+- Unresolved ambiguity or open assumption remains
+- Human has not confirmed phase convergence
+- Low confidence in a subjective/domain decision
+
 ## Final Plan Artifact Template
 
 The **final artifact** (Phase 7 handoff) uses this exact section order, no competing top-level sections — matching GitHub Copilot's native Plan Mode output shape:
@@ -301,14 +323,24 @@ Do not start execution to escape planning discomfort — only start when confide
 
 ## Anti-Patterns
 
-Avoid these common failure modes:
-
-- **Planning theater**: running rounds without real critical thinking. Asking many questions is correct behavior — the anti-pattern is asking hollow, self-validating questions, not asking frequently. Rounds that confirm the plan against itself add false confidence — checks must challenge assumptions, not validate them.
-- **Scope creep silence**: the plan grows beyond the original request without the human noticing. Every addition must be flagged explicitly.
-- **Agent self-validation**: the agent answers its own questions on subjective, domain, or intent-based decisions and proceeds without asking the human. The human is the oracle for domain knowledge, intent, and subjective decisions — the agent must not self-resolve those unilaterally.
-- **Confidence as a proxy for correctness**: an agent expressing certainty does not mean the plan is correct. Run all checks regardless of how confident the agent sounds.
-- **Treating unverified references as facts**: the agent references files, CLIs, statistics, library APIs, quoted sources, or named organizations without a tool call or direct inspection to confirm they exist. All high-risk references must be verified immediately or explicitly listed in the Unverified References section with a mandatory first-step check before use.
-- **Artifact bloat**: the final plan accretes process narrative (Q&A rounds, phase-gate confirmations, todo-list tracking, superseded drafts) instead of converging to the **Final Plan Artifact Template**. It's a continuously-edited deliverable, not an append-only log.
+- **Mistake:** Running Q&A rounds that only confirm the plan against itself.
+  **Why it happens:** Frequent questions look thorough even when they validate rather than challenge.
+  **Instead:** Ask questions that challenge assumptions, not ones that just self-validate.
+- **Mistake:** Letting the plan grow beyond the original request unnoticed.
+  **Why it happens:** Small additions feel harmless one at a time.
+  **Instead:** Flag every addition to the human explicitly.
+- **Mistake:** Answering subjective or domain questions on the agent's own and proceeding.
+  **Why it happens:** It feels faster than waiting for human input.
+  **Instead:** Treat the human as the oracle for domain and subjective decisions.
+- **Mistake:** Treating the agent's own certainty as proof the plan is correct.
+  **Why it happens:** A confident tone feels like validation on its own.
+  **Instead:** Run every check regardless of how confident the agent sounds.
+- **Mistake:** Citing files, APIs, statistics, or sources without verifying they exist.
+  **Why it happens:** Plausible-sounding references are mistaken for confirmed ones.
+  **Instead:** Verify immediately, or list in Unverified References with a first-step check.
+- **Mistake:** Letting the plan accumulate Q&A rounds, gate confirmations, and superseded drafts.
+  **Why it happens:** Process narrative is easy to leave behind when editing in a hurry.
+  **Instead:** Keep the plan a continuously-edited deliverable matching the Final Plan Artifact Template.
 
 ## Re-Plan Triggers
 

package/.xdrs/agentme/edrs/principles/skills/refine-plan-mode/SKILL.test.md

@@ -1,6 +1,6 @@
 ---
 skill: refine-plan-mode
-skill-version: "3.0"
+skill-version: "3.1.0"
 ---
 
 ## Test Scenarios

package/.xdrs/agentme/edrs/principles/skills/refine-user-story/SKILL.md

@@ -7,7 +7,8 @@ description: >
   complete, and ready for implementation.
 metadata:
   author: flaviostutz
-  version: "4.1"
+  version: "4.2.0"
+  updated: 2026-09-21
 ---
 
 ## Overview
@@ -20,6 +21,27 @@ Activate when:
 - The change may affect multiple parts of a system and needs a vertical-slice check.
 - A requirement needs to be refined into a clear, testable story.
 
+### Inputs
+
+#### Required
+- Story request or draft to refine
+
+#### Optional
+- Initiative/epic context, related docs
+
+### Outputs
+
+#### Contents
+- Implementation-ready story, or split stories
+
+#### Changes
+- Story/initiative files under `.assets/`
+
+### Halt Conditions
+- Unresolved ambiguity or open decision remains
+- Human declines to answer a required question
+- Story still too large after a split is proposed
+
 ## Instructions
 
 ### Core Rules
@@ -144,7 +166,7 @@ Before beginning analysis, gather factual context about the system, process, or
 
 #### Step 2 — Requirements loop
 
-Loop asking questions across the 6 areas below until convergence. Apply the Phase navigation rule. A detailed or well-structured input does NOT exempt you from the question loop — treat apparent completeness as a signal to look harder for hidden ambiguities.
+Loop asking questions across the 6 areas below until convergence. Apply the Phase navigation rule and the Core Rules hard gate — a detailed-looking input does not exempt this loop.
 
 **Apply Context Probe rule** throughout this step: whenever a gap in any area could be resolved by an external document, spec, URL, screenshot, or artifact not yet in the Context Summary, ask for it specifically.
 
@@ -157,9 +179,9 @@ Loop asking questions across the 6 areas below until convergence. Apply the Phas
 | Edge cases | What unusual but valid scenarios must work? What invalid inputs or error paths must be handled? What happens on retries, duplicates, partial failure, or missing data? |
 | Dependencies | What upstream or downstream systems affect the change? Are there required approvals, sequencing, or external decisions? Does any migration, rollout, or compatibility concern exist? Is there a real named person — a domain expert, business owner, or decision maker — who can be contacted during implementation if questions arise? (Capture name and role only when they are an actual known person; never fabricate a contact.) |
 
-**Interface and integration scan** (apply Context Probe rule here): before closing Step 2, explicitly check for: external APIs invoked (endpoints, HTTP methods, request/response payloads, authentication, behavior); input/output data (field names, types, formats, valid values, meanings, constraints); documentation links (specs, API references, runbooks); contact names and roles (owners of external systems or business rules); process rules or business logic tied to the story. For any missing detail, ask targeted questions or apply the Context Probe rule to request external sources.
+**Interface and integration scan** (apply Context Probe rule): before closing Step 2, check for external APIs (endpoints, methods, payloads, auth), I/O data (fields, types, formats, constraints), docs/runbooks, contact names/roles, and business rules tied to the story. Ask targeted questions, or apply the Context Probe rule, for anything missing.
 
-Do not proceed to Step 3 while any open decision, unresolved assumption, or ambiguous rule exists. If you find yourself wanting to write "or X" / "TBD" / "to be documented" anywhere, that is a sign you skipped a question.
+Do not proceed to Step 3 while any open decision or ambiguous rule remains (Core Rules hard gate).
 
 #### Step 3 — Scope size evaluation
 
@@ -298,7 +320,7 @@ After all 9 angles converge, use `vscode_askQuestions` (per Phase gate UI rule)
 
 ### Phase 7: Implementer-Perspective Challenge
 
-For each angle, apply the same per-angle protocol defined in Phase 6: generate 10–20 questions about that angle grounded in the current story contents (not generic); attempt to answer each from what has been gathered; for every unanswered question or one that reveals a gap, ask the user via `vscode_askQuestions`; apply the Context Probe rule using implementer-relevant artifacts (an external spec, API reference, interface contract, or similar) when a gap could be resolved by one; mark the angle complete only when every question is answered or explicitly deferred as a named risk; and never resolve a choice point unilaterally. The Phase navigation rule (convergence, Skip, Backtracking) governs loop control on top of this protocol.
+For each angle, apply the Phase 6 per-angle protocol: 10–20 grounded questions, answer what's known, ask the user about gaps via `vscode_askQuestions`, apply the Context Probe rule for implementer artifacts (specs, API references, contracts), and never resolve a choice point unilaterally. The Phase navigation rule governs loop control.
 
 **1. Verifiable acceptance criteria**
 Can every acceptance criterion be independently tested by a developer without ambiguity? Is "done" unambiguous for each item, with no subjective interpretation required? Are criteria specific enough to write automated tests against?
@@ -493,6 +515,18 @@ Apply the same 4 criteria from Phase 2 Step 3. If two or more are met, the story
 - **Request spans multiple independent user outcomes**: always split into separate vertical-slice stories rather than merging into one broad story.
 - **Diagram cannot be generated**: describe the user journey in a plain-language step-by-step walkthrough. The intent of Phase 5 is to externalize the journey — the medium is secondary.
 
+## Anti-Patterns
+
+- **Mistake:** Producing output while a decision is still open.
+  **Why it happens:** The input already looks detailed enough.
+  **Instead:** Apply the hard gate; resolve it via questions first.
+- **Mistake:** Merging independent user outcomes into one story.
+  **Why it happens:** One story feels simpler than several.
+  **Instead:** Split into independently releasable vertical slices.
+- **Mistake:** Treating a skipped Context Probe as unresolved.
+  **Why it happens:** Missing context feels like an open ambiguity.
+  **Instead:** Record it as "not provided," not a blocker.
+
 ## References
 
 - [`agentme-edr-012`](../../012-continuous-xdr-enrichment.md) — Continuous XDR enrichment policy

package/.xdrs/agentme/edrs/principles/skills/refine-user-story/SKILL.test.md

@@ -1,6 +1,6 @@
 ---
 skill: refine-user-story
-skill-version: "4.1"
+skill-version: "4.2.0"
 ---
 
 ## Test Scenarios

package/.xdrs/agentme/edrs/principles/skills/resolve-pr-comments/scripts/update-section.test.js

@@ -90,6 +90,23 @@ test('list renders one bullet block per section, not tab-aligned columns', () =>
   assert.match(stdout, /^ {2}similar-to: review-comment\/333$/m);
 });
 
+test('list --json renders one JSON object per section with the same fields', () => {
+  const file = writeFixture();
+  const { status, stdout } = run(['list', file, '--json']);
+  assert.equal(status, 0);
+  const rows = JSON.parse(stdout);
+  assert.equal(rows.length, 2);
+  assert.equal(rows[0].id, 'issue-comment/111');
+  assert.equal(rows[0].title, 'Contributor offers to help');
+  assert.equal(rows[1].id, 'review-comment/222');
+  assert.equal(rows[1]['author-raw'], 'octocat');
+  assert.equal(rows[1].criticality, 'medium');
+  assert.equal(rows[1]['automation-suggestion'], 'fully-auto');
+  assert.equal(rows[1].action, 'fix');
+  assert.equal(rows[1]['pending-reply'], 'drafted');
+  assert.equal(rows[1]['similar-to'], 'review-comment/333');
+});
+
 test('get returns a scalar field value', () => {
   const file = writeFixture();
   const { status, stdout } = run(['get', file, 'review-comment/222', 'status']);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentme",
-  "version": "0.37.0",
+  "version": "0.37.1",
   "description": "",
   "dependencies": {
     "filedist": "^0.39.0"