claude-dev-env 1.67.2 → 1.69.0

package/skills/autoconverge/CLAUDE.md

@@ -0,0 +1,30 @@
+# autoconverge
+
+**Trigger:** `/autoconverge`, "autoconverge this PR", "converge this PR in one run", "run the converge workflow", "drive the PR to ready autonomously".
+
+Drives one draft PR to convergence in a single autonomous workflow run. Each round runs Cursor Bugbot, a code-review pass, and a bug-audit in parallel on the same HEAD, deduplicates findings, applies every fix in one commit, re-verifies, clears a Copilot wait-gate, and marks the PR ready on convergence. State lives in the workflow journal; no `ScheduleWakeup` ticks.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `reference/` | Markdown docs the skill and workflow cite: round shape, stop conditions, gotchas, and closing report format. |
+| `workflow/` | The `.mjs` convergence workflow, Python report scripts, test files, and the `autoconverge_report_constants/` package. |
+
+## Key files
+
+| File | Role |
+|---|---|
+| `SKILL.md` | Full entry-point protocol: pre-flight steps, worktree setup, `Workflow` call, budget-aware round boundaries, teardown, and the per-round convergence loop summary. |
+| `workflow/converge.mjs` | Main convergence workflow. Runs rounds, gates on Copilot, checks convergence, and marks the PR ready. |
+| `workflow/aggregate_runs.py` | Merges every autoconverge journal for a PR into one deduped journal. |
+| `workflow/convergence_summary.py` | Builds the convergence-summary agent prompt over the merged findings. |
+| `workflow/render_report.py` | Builds the closing HTML report from the merged journal and summary. |
+| `reference/convergence.md` | Round shape: the three parallel lenses, deduplication, fix commit, and the ready definition. |
+| `reference/stop-conditions.md` | Every way the run ends short of ready. |
+| `reference/gotchas.md` | Hard-won failure lessons. |
+| `reference/closing-report.md` | Specification for the closing HTML report format. |
+
+## Entry point
+
+Requires the `Workflow` tool. The `SKILL.md` body specifies the exact pre-flight sequence and `Workflow` call.

package/skills/autoconverge/reference/CLAUDE.md

@@ -0,0 +1,12 @@
+# reference
+
+Reference documentation for the `autoconverge` skill. The `converge.mjs` workflow and the `SKILL.md` cite these files to define behavior precisely.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `convergence.md` | Round shape: the three parallel lenses (Bugbot, code-review, bug-audit), deduplication, the fix commit step, and the definition of a clean convergence. |
+| `stop-conditions.md` | Every condition that ends the run short of ready: budget cap, iteration cap, blocker exit, Copilot bypass. |
+| `gotchas.md` | Hard-won lessons from failed runs: PR title validation, conflicting PRs, worktree branch lock, resumed sessions rerooting, and minter issues. |
+| `closing-report.md` | Specification for the closing HTML convergence report the teardown step builds and publishes. |

package/skills/autoconverge/workflow/CLAUDE.md

@@ -0,0 +1,23 @@
+# workflow
+
+Workflow scripts and report utilities for the `autoconverge` skill.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `converge.mjs` | Main convergence workflow script. Each round runs Bugbot, code-review, and bug-audit lenses in parallel, deduplicates findings, applies fixes, pushes, gates on Copilot, checks convergence, and marks the PR ready. Runs via the `Workflow` tool — not directly with Node. |
+| `aggregate_runs.py` | Merges every autoconverge journal for a given PR (matched by run id) into one merged journal. Prints a JSON line with `mergedJournal`, `roundCount`, `finalSha`, and `findingCount`. |
+| `convergence_summary.py` | Builds the convergence-summary agent prompt over the merged journal's findings. The teardown step spawns a `general-purpose` subagent on this prompt. |
+| `render_report.py` | Builds the closing HTML insights report. Takes `--journal`, `--summary-file`, `--out`, `--pr`, `--final-sha`, and `--rounds`. Writes the HTML to `--out` and prints the output path on stdout. |
+| `autoconverge_report_constants/` | Named constants package for `render_report.py` and `convergence_summary.py`. |
+| `converge.contract.test.mjs` | Contract tests for `converge.mjs` — verify the workflow interface and step ordering. |
+| `converge.clean-audit.test.mjs` | Tests the clean-audit path (all lenses clean on first round). |
+| `converge.copilot-gate.test.mjs` | Tests Copilot gate behavior (bypass on quota exhaustion). |
+| `converge.fix-progress.test.mjs` | Tests fix-progress tracking across rounds. |
+| `converge.fix-recovery.test.mjs` | Tests recovery when a fix commit fails. |
+| `converge.run-input.test.mjs` | Tests workflow input validation. |
+| `test_aggregate_runs.py` | Tests for `aggregate_runs.py`. |
+| `test_convergence_summary.py` | Tests for `convergence_summary.py`. |
+| `test_render_report.py` | Tests for `render_report.py`. |
+| `fixtures/` | Test fixture data for the workflow tests. |

package/skills/autoconverge/workflow/autoconverge_report_constants/CLAUDE.md

@@ -0,0 +1,16 @@
+# autoconverge_report_constants
+
+Python package of named constants for `render_report.py` and `convergence_summary.py` in the `autoconverge/workflow/` directory.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `__init__.py` | Package marker. |
+| `render_report_constants.py` | Named constants for the report renderer: structured output tool name, journal label prefixes (`resolve-head`, `lens:`, `fix:`, `copilot-gate`, `convergence-summary`), journal sibling directory names, default finding category and severity, date and SHA length constants, workflow name, projects directory name, merged run id prefix, summary detail character limit, and `onexc` Python version threshold. |
+
+## Usage
+
+```python
+from autoconverge_report_constants.render_report_constants import LABEL_PREFIX_LENS
+```

package/skills/autoconverge/workflow/converge.fix-recovery.test.mjs

@@ -183,3 +183,138 @@ test('the round-loop fix-stalled blockers survive the recovery wiring', () => {
   assert.match(convergeSource, /fix lens landed no push for/);
   assert.match(convergeSource, /copilot fix lens landed no push for/);
 });
+
+const verifyObjectionModule = new Function(
+  `${constantLine('VERIFY_OBJECTION_FALLBACK')}\n` +
+    `${functionSource('renderVerifyObjectionLine')}\n` +
+    `${functionSource('extractVerifyObjection')}\n` +
+    'return { extractVerifyObjection, VERIFY_OBJECTION_FALLBACK };',
+)();
+
+const { extractVerifyObjection, VERIFY_OBJECTION_FALLBACK } = verifyObjectionModule;
+
+test('extractVerifyObjection falls back for a non-string transcript', () => {
+  assert.equal(extractVerifyObjection(null), VERIFY_OBJECTION_FALLBACK);
+});
+
+test('extractVerifyObjection falls back when no verdict fence is present', () => {
+  assert.equal(
+    extractVerifyObjection('the verifier wrote prose with no verdict fence'),
+    VERIFY_OBJECTION_FALLBACK,
+  );
+});
+
+test('extractVerifyObjection falls back when the verdict fence carries no findings', () => {
+  const transcript = '```verdict\n{"all_pass": false, "findings": []}\n```';
+  assert.equal(extractVerifyObjection(transcript), VERIFY_OBJECTION_FALLBACK);
+});
+
+test('extractVerifyObjection renders each verdict finding as check then detail', () => {
+  const transcript =
+    '```verdict\n{"all_pass": false, "findings": [{"check": "Finding 1", "detail": "still over-blocks"}, {"check": "Finding 2", "detail": "boundary unchecked"}]}\n```';
+  const objection = extractVerifyObjection(transcript);
+  assert.match(objection, /1\. Finding 1 — still over-blocks/);
+  assert.match(objection, /2\. Finding 2 — boundary unchecked/);
+});
+
+test('extractVerifyObjection reads the LAST verdict fence', () => {
+  const transcript =
+    '```verdict\n{"all_pass": false, "findings": [{"check": "stale", "detail": "old"}]}\n```\nretry\n```verdict\n{"all_pass": false, "findings": [{"check": "fresh", "detail": "new"}]}\n```';
+  const objection = extractVerifyObjection(transcript);
+  assert.match(objection, /fresh — new/);
+  assert.doesNotMatch(objection, /stale/);
+});
+
+test('extractVerifyObjection renders bare string findings as their text', () => {
+  const transcript =
+    '```verdict\n{"all_pass": false, "findings": ["boundary still over-blocks", "missing test for empty input"]}\n```';
+  const objection = extractVerifyObjection(transcript);
+  assert.match(objection, /1\. boundary still over-blocks/);
+  assert.match(objection, /2\. missing test for empty input/);
+  assert.doesNotMatch(objection, /unnamed check/);
+});
+
+test('extractVerifyObjection renders alternate-keyed objects (title, message, description, issue)', () => {
+  const transcript =
+    '```verdict\n{"all_pass": false, "findings": [{"title": "over-blocks", "detail": "boundary unchecked"}, {"message": "regex too broad"}, {"description": "no fallback path"}, {"issue": "stale fixture"}]}\n```';
+  const objection = extractVerifyObjection(transcript);
+  assert.match(objection, /over-blocks — boundary unchecked/);
+  assert.match(objection, /regex too broad/);
+  assert.match(objection, /no fallback path/);
+  assert.match(objection, /stale fixture/);
+  assert.doesNotMatch(objection, /unnamed check/);
+  assert.doesNotMatch(objection, /no detail/);
+});
+
+test('extractVerifyObjection renders mixed string and object findings', () => {
+  const transcript =
+    '```verdict\n{"all_pass": false, "findings": ["plain concern", {"check": "named", "detail": "explained"}]}\n```';
+  const objection = extractVerifyObjection(transcript);
+  assert.match(objection, /1\. plain concern/);
+  assert.match(objection, /2\. named — explained/);
+});
+
+test('extractVerifyObjection stringifies an object whose keys it does not recognize', () => {
+  const transcript = '```verdict\n{"all_pass": false, "findings": [{"severity": "P1", "line": 42}]}\n```';
+  const objection = extractVerifyObjection(transcript);
+  assert.match(objection, /severity/);
+  assert.match(objection, /42/);
+  assert.doesNotMatch(objection, /unnamed check/);
+});
+
+test('extractVerifyObjection falls back when no finding yields usable text', () => {
+  const transcript = '```verdict\n{"all_pass": false, "findings": [null, {}, ""]}\n```';
+  assert.equal(extractVerifyObjection(transcript), VERIFY_OBJECTION_FALLBACK);
+});
+
+test('recoverVerifyFailEdit is a clean-coder edit step bound to the verifier objection and leaves changes uncommitted', () => {
+  const recoverBody = functionSource('recoverVerifyFailEdit');
+  assert.match(recoverBody, /agentType:\s*'clean-coder'/, 'expected the fixer to use clean-coder');
+  assert.match(recoverBody, /schema:\s*EDIT_SCHEMA/, 'expected the fixer to reuse EDIT_SCHEMA');
+  assert.match(recoverBody, /label:\s*`fix-verify-recover:/, 'expected the fix-verify-recover label');
+  assert.match(recoverBody, /objection/, 'expected the fixer prompt to consume the verifier objection');
+  assert.match(
+    recoverBody,
+    /do not commit and do not push|Do NOT commit|leave .*uncommitted|uncommitted/i,
+    'expected the fixer to leave its fix uncommitted for the re-verify and retry commit',
+  );
+});
+
+test('verifyWithRecovery bounds the loop, re-fixes on a failed verdict, and re-verifies', () => {
+  const recoveryBody = functionSource('verifyWithRecovery');
+  assert.match(recoveryBody, /verdictPassed\(/, 'expected the loop guard to call verdictPassed');
+  assert.match(
+    recoveryBody,
+    /attempt\s*<\s*FIX_RECOVERY_MAX_ATTEMPTS/,
+    'expected the loop to be bounded by FIX_RECOVERY_MAX_ATTEMPTS',
+  );
+  assert.match(recoveryBody, /runRecoverEdit\(/, 'expected the loop to spawn the verify-recovery fixer');
+  assert.match(recoveryBody, /runVerify\(/, 'expected the loop to re-verify after the fixer edit');
+  assert.match(
+    recoveryBody,
+    /extractVerifyObjection\(/,
+    'expected the loop to feed the fixer the verifier objection',
+  );
+  const editGuardIndex = recoveryBody.search(/edited\s*!==\s*true/);
+  assert.notEqual(editGuardIndex, -1, 'expected an early break when the fixer made no edit');
+  const recoverEditIndex = recoveryBody.search(/runRecoverEdit\(/);
+  const reverifyIndex = recoveryBody.lastIndexOf('runVerify(');
+  assert.ok(recoverEditIndex < reverifyIndex, 'expected order recover-edit -> re-verify, so a swap fails');
+});
+
+test('applyFixes routes its verify through verifyWithRecovery before commitWithRecovery', () => {
+  const applyFixesBody = functionSource('applyFixes');
+  assert.match(applyFixesBody, /verifyWithRecovery\(/, 'expected applyFixes to call verifyWithRecovery');
+  assert.match(applyFixesBody, /runVerify:\s*\(\)\s*=>\s*verifyFixesInWorkingTree\(/);
+  assert.match(applyFixesBody, /runRecoverEdit:[\s\S]*?recoverVerifyFailEdit\(/);
+  const verifyIndex = applyFixesBody.search(/verifyWithRecovery\(/);
+  const commitIndex = applyFixesBody.search(/commitWithRecovery\(/);
+  assert.ok(verifyIndex < commitIndex, 'expected verify-recovery to precede commit-recovery');
+});
+
+test('repairConvergence routes its verify through verifyWithRecovery wired to the repair verify step', () => {
+  const repairBody = functionSource('repairConvergence');
+  assert.match(repairBody, /verifyWithRecovery\(/, 'expected repairConvergence to call verifyWithRecovery');
+  assert.match(repairBody, /runVerify:\s*\(\)\s*=>\s*verifyRepairChanges\(/);
+  assert.match(repairBody, /runRecoverEdit:[\s\S]*?recoverVerifyFailEdit\(/);
+});

package/skills/autoconverge/workflow/converge.mjs

@@ -406,6 +406,68 @@ function verdictPassed(verifyTranscript) {
   }
 }
 
+const VERIFY_OBJECTION_FALLBACK = 'The verify step rejected the working-tree fixes without a parseable verdict; re-read the fix-verify transcript above and address every concern it raised.'
+
+/**
+ * Render one verdict finding as a single objection line, tolerant of the shapes a
+ * verifier realistically emits: a bare string, an object keyed by any of
+ * check/title/message/description/issue for the headline and detail/description
+ * for the body, or any other object (stringified so its content survives). A
+ * headline and a detail render as "headline — detail"; a headline alone renders
+ * as the headline; an entry that yields no usable text returns null so the caller
+ * can fall back rather than emit a content-free placeholder.
+ * @param {unknown} eachFinding one entry from the verdict findings array
+ * @returns {string|null} the rendered objection line, or null when unusable
+ */
+function renderVerifyObjectionLine(eachFinding) {
+  if (typeof eachFinding === 'string') {
+    const trimmedFinding = eachFinding.trim()
+    return trimmedFinding.length > 0 ? trimmedFinding : null
+  }
+  if (eachFinding === null || typeof eachFinding !== 'object') return null
+  const headline =
+    eachFinding.check || eachFinding.title || eachFinding.message || eachFinding.description || eachFinding.issue
+  const detail = eachFinding.detail || (headline === eachFinding.description ? '' : eachFinding.description)
+  if (typeof headline === 'string' && headline.length > 0) {
+    return typeof detail === 'string' && detail.length > 0 ? `${headline} — ${detail}` : headline
+  }
+  const stringifiedFinding = JSON.stringify(eachFinding)
+  return stringifiedFinding === '{}' ? null : stringifiedFinding
+}
+
+/**
+ * Pull the verifier's stated objections out of a failed verify transcript so the
+ * re-fix step knows what the verdict rejected. Reads the last fenced verdict JSON
+ * (the same block verdictPassed reads) and renders each finding through
+ * renderVerifyObjectionLine into a numbered list. A missing fence, a parse
+ * failure, an empty findings list, or a findings list where no entry yields
+ * usable text falls back to a generic re-read instruction, so the re-fix step
+ * always receives actionable text.
+ * @param {string|null|undefined} verifyTranscript the failed verifier transcript text
+ * @returns {string} a human-readable block of the verifier's objections
+ */
+function extractVerifyObjection(verifyTranscript) {
+  if (typeof verifyTranscript !== 'string') return VERIFY_OBJECTION_FALLBACK
+  const fencePattern = /```verdict\s*\n([\s\S]*?)```/g
+  let lastFenceBody = null
+  let eachMatch
+  while ((eachMatch = fencePattern.exec(verifyTranscript)) !== null) {
+    lastFenceBody = eachMatch[1]
+  }
+  if (lastFenceBody === null) return VERIFY_OBJECTION_FALLBACK
+  try {
+    const verdictRecord = JSON.parse(lastFenceBody)
+    const allObjections = Array.isArray(verdictRecord?.findings) ? verdictRecord.findings : []
+    const renderedObjections = allObjections
+      .map((eachFinding) => renderVerifyObjectionLine(eachFinding))
+      .filter((eachLine) => eachLine !== null)
+    if (renderedObjections.length === 0) return VERIFY_OBJECTION_FALLBACK
+    return renderedObjections.map((eachLine, position) => `${position + 1}. ${eachLine}`).join('\n')
+  } catch {
+    return VERIFY_OBJECTION_FALLBACK
+  }
+}
+
 /**
  * Decide whether a fix lens actually advanced the round: a pushed fix that moved
  * HEAD progressed, and so did an all-stale round whose findings were every one
@@ -808,6 +870,32 @@ function recoverCommitBlockEdit(head, blockerDetail, sourceLabel, attempt) {
   )
 }
 
+/**
+ * Verify-recovery fixer: when the verify step rejects the working-tree fixes, one
+ * clean-coder re-fixes against the verdict's stated objections, test-first, and
+ * leaves the work uncommitted so the re-verify step can bind a fresh verdict. The
+ * objection text names which findings the verifier judged unresolved and why, so
+ * the fixer addresses those concerns; it does not touch GitHub review threads —
+ * the edit step already replied to and resolved those.
+ * @param {string} head PR HEAD SHA the fixes were raised against
+ * @param {string} objection the verifier's rendered objections from the failed verdict
+ * @param {string} sourceLabel short description of where the findings came from
+ * @param {number} attempt the 1-based recovery attempt number
+ * @returns {Promise<object>} EDIT_SCHEMA result
+ */
+function recoverVerifyFailEdit(head, objection, sourceLabel, attempt) {
+  return convergeAgent(
+    `You are the VERIFY-RECOVERY fixer (attempt ${attempt}) for fixes (${sourceLabel}) on ${prCoordinates}, HEAD ${head}. The verify step rejected the working-tree fixes; its verdict named what is still unresolved. A separate verify step then a separate commit step run after you.\n\n` +
+      `The verify step's objections:\n${objection}\n\n` +
+      `Rules:\n` +
+      `- Confirm the working tree is on the PR branch at HEAD ${head} with the prior fixes still present.\n` +
+      `- Address every objection above test-first (failing test, then minimum code to pass) per CODE_RULES, so each named concern is genuinely resolved the way the verdict requires. Do not touch GitHub review threads — the edit step already handled those.\n` +
+      `- Leave the corrected fixes in the working tree. Do NOT commit and do NOT push — the verify step re-binds a verdict and the commit step pushes after you.\n\n` +
+      `Return values: edited=true with a one-line summary when you changed code to address the objections; edited=false, resolvedWithoutCommit=false when the objections cannot be cleared with a code change.`,
+    { label: `fix-verify-recover:${sourceLabel}`, phase: 'Converge', schema: EDIT_SCHEMA, agentType: 'clean-coder' },
+  )
+}
+
 const FIX_RECOVERY_MAX_ATTEMPTS = 2
 
 /**
@@ -836,6 +924,29 @@ async function commitWithRecovery({ runCommit, runVerify, runRecoverEdit }) {
   return commitResult
 }
 
+/**
+ * Run the verify step and, when its verdict fails, route back to a fixer: re-fix
+ * against the verifier's objection, then re-verify — bounded by
+ * FIX_RECOVERY_MAX_ATTEMPTS. The loop breaks early when the fixer makes no edit,
+ * returning the last failed verify transcript so the caller's verdict-failed
+ * handling still applies; a verify that passes on any attempt returns its passing
+ * transcript so the caller proceeds to commit.
+ * @param {{runVerify: function, runRecoverEdit: function}} steps the verify and verify-recovery-edit thunks
+ * @returns {Promise<string>} the final verify transcript — passing, or the last failed one
+ */
+async function verifyWithRecovery({ runVerify, runRecoverEdit }) {
+  let verifyTranscript = await runVerify()
+  let attempt = 0
+  while (!verdictPassed(verifyTranscript) && attempt < FIX_RECOVERY_MAX_ATTEMPTS) {
+    attempt += 1
+    const objection = extractVerifyObjection(verifyTranscript)
+    const recoverEdit = await runRecoverEdit(objection, attempt)
+    if (recoverEdit?.edited !== true) break
+    verifyTranscript = await runVerify()
+  }
+  return verifyTranscript
+}
+
 /**
  * Fix lens: edit (clean-coder, no commit) -> verify (code-verifier emits a
  * verdict fence binding the working tree) -> commit (clean-coder, one commit +
@@ -862,7 +973,10 @@ async function applyFixes(head, findings, sourceLabel) {
       blockerDetail: '',
     }
   }
-  const verifyTranscript = await verifyFixesInWorkingTree(head, findings, sourceLabel)
+  const verifyTranscript = await verifyWithRecovery({
+    runVerify: () => verifyFixesInWorkingTree(head, findings, sourceLabel),
+    runRecoverEdit: (objection, attempt) => recoverVerifyFailEdit(head, objection, sourceLabel, attempt),
+  })
   if (!verdictPassed(verifyTranscript)) {
     return {
       newSha: head,
@@ -1099,7 +1213,10 @@ async function repairConvergence(head, failures) {
       blockerDetail: '',
     }
   }
-  const verifyTranscript = await verifyRepairChanges(head, failures)
+  const verifyTranscript = await verifyWithRecovery({
+    runVerify: () => verifyRepairChanges(head, failures),
+    runRecoverEdit: (objection, attempt) => recoverVerifyFailEdit(head, objection, 'repair', attempt),
+  })
   if (!verdictPassed(verifyTranscript)) {
     return {
       newSha: head,

package/skills/bdd-protocol/CLAUDE.md

@@ -0,0 +1,26 @@
+# bdd-protocol
+
+**Trigger:** `/bdd-protocol`, "Example Mapping", "BDD anti-patterns", "§7.6", writing executable specifications, BDD scenario quality, "the one where" discovery examples.
+
+On-demand BDD depth layered on top of the always-on `<behavior_protocol>` in the system prompt. The skill adds the Example Mapping algorithm (Smart & Molak §6.4), the scenario quality catalog (§7.6), outside-in test layout, and solo BDD patterns.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `references/` | Loaded reference docs: Example Mapping algorithm and the anti-patterns catalog. |
+
+## Key files
+
+| File | Role |
+|---|---|
+| `SKILL.md` | Entry point. `@`-imports both reference files so they load with the skill. Lists authorities and scope boundaries. |
+| `references/example-mapping.md` | Example Mapping algorithm: core moves ("The one where …"), the chat algorithm for solo use, time-boxing guidance. Source: Smart & Molak §6.4. |
+| `references/anti-patterns.md` | §7.6 scenario quality catalog: anti-patterns to avoid and the criteria for a good scenario. |
+
+## What the skill adds
+
+The base `<behavior_protocol>` (Deliberate Discovery → Illustrate → Formulate → Automate) is always active. This skill adds depth only when:
+- The task needs Example Mapping steps or parking-lot question management.
+- Scenarios need the §7.6 quality bar applied.
+- Tests need outside-in layout using describe / when / should.

package/skills/bdd-protocol/references/CLAUDE.md

@@ -0,0 +1,10 @@
+# references
+
+Reference documentation loaded by the `bdd-protocol` skill. Both files are `@`-imported in `SKILL.md` and load when the skill activates.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `example-mapping.md` | Example Mapping algorithm (Smart & Molak §6.4). Covers core moves, the "The one where …" phrasing, probes, parking-lot questions, the solo chat algorithm, and time-boxing guidance. |
+| `anti-patterns.md` | §7.6 scenario quality catalog. Lists anti-patterns to avoid and the criteria for a well-formed BDD scenario. |

package/skills/bg-agent/CLAUDE.md

@@ -0,0 +1,17 @@
+# bg-agent
+
+Delegates a task to a background agent so the main session stays free. Triggered by `/bg-agent`, `bg-agent`, or `background agent for this`.
+
+## Purpose
+
+This skill picks a suitable agent type for the task, spawns it via the `Agent` tool with `run_in_background: true`, and returns control at once. The spawned agent notifies on completion. Other skills (such as `gotcha`) invoke this skill to offload their own PR-creation steps.
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Full instructions: how to parse the task argument, how to pick an agent type, how to write a self-contained spawn prompt, and how to report spawn to the user. |
+
+## How this skill is invoked
+
+The user types `/bg-agent <task description>` or a calling skill invokes it by name. The skill always spawns with `run_in_background: true` — it never runs the task inline in the main session.

package/skills/bugteam/CLAUDE.md

@@ -0,0 +1,30 @@
+# bugteam
+
+Runs an audit-fix loop on an open pull request until all findings are resolved or the 20-loop cap is reached. Triggered by `/bugteam`, `run the bug team`, `auto-fix the PR until clean`, or `loop audit and fix`.
+
+## Purpose
+
+Each loop: a `code-quality-agent` (fresh context, all A–P audit categories) produces an outcome XML; a `clean-coder` agent applies every fix; the lead commits, pushes, and posts a GitHub PR review (APPROVE on clean, REQUEST_CHANGES with inline anchored comments on dirty). Grants `.claude/**` write permissions at the start and revokes them at the end.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Hub — pre-flight call, refusals, audit-posting protocol, progress checklist, and situation-to-reference table. Read this first. |
+| `PROMPTS.md` | Spawn XML, A–P category bindings, outcome XML schemas. |
+| `CONSTRAINTS.md` | Invariants — what the loop must never violate. |
+| `EXAMPLES.md` | Exit scenarios: converged, cap-reached, stuck, refusal, mixed-outcome. |
+| `sources.md` | Doc URLs and verbatim quotes cited in the skill body. |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `reference/` | Expanded workflow detail loaded on demand (team setup, audit contract, GitHub PR review shape, teardown). |
+| `scripts/` | Python scripts executed by the lead or teammates at runtime. |
+
+## Environment controls
+
+- `CLAUDE_REVIEWS_DISABLED=bugteam` — disables the skill entirely (pre-flight exits 7).
+- `BUGTEAM_PREFLIGHT_SKIP=1` — skips pytest in pre-flight.
+- `BUGTEAM_REVIEWER_ACCOUNT=<login>` — names the alternate `gh` account for posting reviews when the PR author and reviewer identity match.

package/skills/bugteam/reference/CLAUDE.md

@@ -0,0 +1,22 @@
+# bugteam/reference
+
+Expanded workflow detail for the `bugteam` skill. Load a file from this directory when the orchestration stub in `SKILL.md` is not enough — for example, when debugging GitHub review shape, understanding gate semantics, or working through teardown edge cases.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `README.md` | Index of all files in this directory with one-line domain summaries. |
+| `team-setup.md` | Permissions grant, PR scope resolution, run name, temp dir, and loop state. |
+| `audit-and-teammates.md` | Pre-audit CODE_RULES gate, full cycle numbering, AUDIT and FIX action detail. |
+| `audit-contract.md` | Finding shape (Shape A / B), Haiku secondary merge rules, post-fix self-audit. |
+| `github-pr-reviews.md` | Per-loop review posting, `jq`+`gh api` payloads, inline anchors, fallbacks, REST endpoints. |
+| `teardown-publish-permissions.md` | Teardown steps, PR description rewrite via `pr-description-writer`, permission revoke, final report. |
+| `design-rationale.md` | Why clean-room subagents, when `/bugteam` applies, refusal reasons. |
+| `copilot-gap-analysis.md` | Historical gap analysis (reference only). |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `obstacles/` | Per-step obstacle guides — one file per common failure point (e.g., write XML, resolve thread, push, test suite). |

package/skills/bugteam/reference/obstacles/CLAUDE.md

@@ -0,0 +1,24 @@
+# bugteam/reference/obstacles
+
+Per-step obstacle guides for the `bugteam` skill. Each file addresses a specific failure point that can occur during an audit-fix loop. Load the matching file when a step fails rather than improvising a fix.
+
+## Files
+
+| File | Obstacle it addresses |
+|---|---|
+| `audit-assign-ids.md` | Assigning stable finding IDs in the audit output. |
+| `audit-capture-excerpts.md` | Capturing code excerpts for each finding. |
+| `audit-walk-categories.md` | Walking all A–P categories without skipping. |
+| `audit-write-xml.md` | Writing the outcome XML from an audit pass. |
+| `fix-append-summary.md` | Appending the fix summary to the outcome XML. |
+| `fix-apply-fixes.md` | Applying code fixes from the finding list. |
+| `fix-git-add-commit.md` | Staging and committing the fixed files. |
+| `fix-git-push.md` | Pushing the fix commit to the remote branch. |
+| `fix-post-reply.md` | Posting inline replies to finding threads on the PR. |
+| `fix-publish-summary.md` | Publishing the loop summary to the PR. |
+| `fix-py-compile.md` | Verifying Python syntax after fixes. |
+| `fix-read-files.md` | Reading the files referenced in a finding. |
+| `fix-resolve-thread.md` | Resolving a finding's review thread on GitHub. |
+| `fix-test-suite.md` | Running the test suite and interpreting failures. |
+| `fix-violation-count.md` | Counting open violations after a fix pass. |
+| `fix-write-xml.md` | Writing the per-fix XML record. |

package/skills/bugteam/scripts/CLAUDE.md

@@ -0,0 +1,36 @@
+# bugteam/scripts
+
+Python scripts executed by the bugteam lead or teammates at runtime. These are not loaded into context as instructions — they run as subprocess calls from within the skill workflow.
+
+## Scripts
+
+| File | Purpose |
+|---|---|
+| `bugteam_preflight.py` | Run pytest and optional `pre-commit` before the first loop. Skips pytest when `BUGTEAM_PREFLIGHT_SKIP=1` or no test files exist. |
+| `bugteam_fix_hookspath.py` | Auto-remediate a stale `core.hooksPath` override, set the canonical global value, re-run preflight. |
+| `bugteam_code_rules_gate.py` | Run `validate_content` from `code_rules_enforcer.py` on PR-scoped files. Exit 1 on mandatory rule failures. |
+| `grant_project_claude_permissions.py` | Grant Edit/Write/Read on `cwd/.claude/**` in `~/.claude/settings.json`. |
+| `revoke_project_claude_permissions.py` | Remove the matching grant entries from `~/.claude/settings.json`. |
+| `_bugteam_permissions_common.py` | Shared helpers for grant/revoke (atomic JSON writes, settings sections). |
+| `windows_safe_rmtree.py` | Remove a directory tree on Windows by stripping ReadOnly attributes and retrying on failure. |
+| `probe_code_rules_enforcer_check.py` | Load `code_rules_enforcer.py` and invoke a named check function against a fixture file. |
+| `reflow_skill_md.py` | Reflow the bugteam SKILL.md body to fit line-length limits. |
+
+## Test files
+
+| File | Tests |
+|---|---|
+| `test_bugteam_preflight.py` | `bugteam_preflight.py` |
+| `test_bugteam_code_rules_gate.py` | `bugteam_code_rules_gate.py` |
+| `test_bugteam_fix_hookspath.py` | `bugteam_fix_hookspath.py` |
+| `test_bugteam_permissions_common.py` | `_bugteam_permissions_common.py` |
+| `test__bugteam_permissions_common.py` | Internal helpers in `_bugteam_permissions_common.py` |
+| `test_agent_config_carveout.py` | `.claude/**` grant/revoke carveout logic |
+| `test_probe_code_rules_enforcer_check.py` | `probe_code_rules_enforcer_check.py` |
+| `test_windows_safe_rmtree.py` | `windows_safe_rmtree.py` |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `bugteam_scripts_constants/` | Named constants imported by the scripts above. |

package/skills/bugteam/scripts/bugteam_scripts_constants/CLAUDE.md

@@ -0,0 +1,20 @@
+# bugteam/scripts/bugteam_scripts_constants
+
+Python package of named constants imported by the bugteam scripts. Each module holds the constants for one script; importing from this package keeps magic values out of the script bodies.
+
+## Modules
+
+| File | Constants for |
+|---|---|
+| `bugteam_preflight_constants.py` | `bugteam_preflight.py` — env var name, hooks path suffix, exit codes, ignore dirs, argument tuples, config filenames. |
+| `bugteam_code_rules_gate_constants.py` | `bugteam_code_rules_gate.py` — gate-related path and exit-code constants. |
+| `bugteam_fix_hookspath_constants.py` | `bugteam_fix_hookspath.py` — canonical hooks path, remediation message strings. |
+| `claude_permissions_common_constants.py` | `_bugteam_permissions_common.py` — settings JSON keys, glob patterns for the grant/revoke scripts. |
+| `probe_code_rules_enforcer_check_constants.py` | `probe_code_rules_enforcer_check.py` — enforcer module path and function name constants. |
+| `reflow_skill_md_constants.py` | `reflow_skill_md.py` — line-length and formatting constants. |
+| `windows_safe_rmtree_constants.py` | `windows_safe_rmtree.py` — retry count and wait constants. |
+| `__init__.py` | Empty package marker. |
+
+## Convention
+
+Scripts import from this package at module scope. No constant is defined inline in a script body — the hook enforces this at write time.

package/skills/caveman/CLAUDE.md

@@ -0,0 +1,15 @@
+# caveman
+
+Trims noise from conversational text in the current turn. Triggered by `/caveman`, `caveman this`, `trim this`, `make it terse`, or `caveman voice`.
+
+## Purpose
+
+The inline counterpart to the `caveman` agent. When the user wants preamble, hedging, filler transitions, restatements, empty future-proofing, dead examples, or pleasantries stripped from the last assistant message or from text passed as an argument, this skill performs the trim directly in the main session — no `Agent` spawn. The entire reply is the trimmed text; no report, no commentary about what was cut.
+
+Use the `caveman` agent (`subagent_type: caveman`) when the input is a file path, a multi-section artifact that needs a structured report, or a delegated workflow.
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Instructions: resolve the source (argument or prior message), noise categories to cut, what to preserve verbatim, and the escape hatch for load-bearing spans. |

package/skills/code/CLAUDE.md

@@ -0,0 +1,17 @@
+# code
+
+Activates strict code standards for the entire implementation session. Triggered by `/code`, `code standards`, `strict code`, `enforce standards`, or `implement with standards`.
+
+## Purpose
+
+Prepends a set of binary completion criteria to every implementation task: no `Any`, no `cast()`, no `# type: ignore`, treated-as-immutable TypedDicts with explicit `_encode_*`/`_decode_*` functions, 100% statement and branch coverage, zero mocks, zero stubs, zero fallbacks, and proper module structure. Every criterion is pass-or-fail; partial credit does not exist.
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Sixteen numbered criteria (typing strictness, error handling, test coverage, DI hooks, DRY, TypedDict protocol, Redis boundary, TOML boundary, JSON recursive types, ASGI boundaries, dynamic import pattern, documentation, build infrastructure, lint gates, Protocol signature match, auth/credentials), plus gotchas for Windows PowerShell invocation and per-module `_test_hooks.py` placement. |
+
+## Invocation note
+
+Invoke at the start of an implementation task. The standards persist for the full session. The skill refuses research or planning tasks and redirects them to `/anthropic-plan`.

package/skills/copilot-review/CLAUDE.md

@@ -0,0 +1,17 @@
+# copilot-review
+
+Spawns a background subagent that polls the GitHub Copilot reviewer on the current PR, fixes unaddressed findings, and re-requests review each tick until the PR is clean. Triggered by `/copilot-review`, `watch copilot`, `babysit copilot review`, or `keep re-requesting copilot`.
+
+## Purpose
+
+The main session gathers PR context (number, HEAD SHA, owner/repo, branch), spawns a self-terminating background subagent with a fully filled-in prompt, and returns control at once. The subagent loops on a 5-minute `ScheduleWakeup` cadence: fetch Copilot's latest review, TDD-fix any inline findings, push a commit, reply inline, re-request review. It stops on convergence, a persistent blocker, `TaskStop`, or after 20 ticks.
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Four-step orchestration (opt-out check, gather PR context, spawn subagent, report to user), the verbatim subagent prompt template with all placeholders, fix protocol, stop conditions, and ground rules (one commit per tick, honor hooks, preserve draft state, use `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix). |
+
+## Environment opt-out
+
+Set `CLAUDE_REVIEWS_DISABLED=copilot` to disable. The skill checks this before spawning anything.