claude-dev-env 1.36.1 → 1.37.0

package/skills/bugteam/scripts/reflow_skill_md.py

@@ -17,14 +17,15 @@ from __future__ import annotations
 
 import re
 import textwrap
-from pathlib import Path
 
-MAX_WIDTH = 80
-SKILL_PATH = Path(__file__).resolve().parent.parent / "SKILL.md"
-
-ORDERED_RE = re.compile(r"^(\s*)(\d+\.\s)(.*)$")
-BULLET_RE = re.compile(r"^(\s*)([-*]\s)(.*)$")
-UNFINISHED_MD_LINK_TARGET = re.compile(r"\]\([^)]*$")
+from config.reflow_skill_md_constants import (
+    BASH_CONTINUATION_MARKER_WIDTH,
+    BULLET_LIST_ITEM_PATTERN as BULLET_RE,
+    MAXIMUM_LINE_WIDTH as MAX_WIDTH,
+    ORDERED_LIST_ITEM_PATTERN as ORDERED_RE,
+    TARGET_SKILL_PATH as SKILL_PATH,
+    UNFINISHED_MARKDOWN_LINK_TARGET_PATTERN as UNFINISHED_MD_LINK_TARGET,
+)
 
 
 def wrap_paragraph_plain(text: str) -> list[str]:
@@ -55,11 +56,14 @@ def wrap_list_item(lead_ws: str, marker: str, body: str) -> list[str]:
     ).splitlines()
 
 
-def reflow_yaml_description_block(lines: list[str], body_start: int) -> tuple[list[str], int]:
+def reflow_yaml_description_block(
+    all_lines: list[str],
+    body_start: int,
+) -> tuple[list[str], int]:
     body_parts: list[str] = []
     index = body_start
-    while index < len(lines):
-        line = lines[index]
+    while index < len(all_lines):
+        line = all_lines[index]
         if line.strip() == "---":
             index += 1
             break
@@ -118,30 +122,30 @@ def merge_without_space(buffer: str, continuation: str) -> bool:
     return False
 
 
-def merge_soft_breaks(lines: list[str]) -> list[str]:
-    output: list[str] = []
+def merge_soft_breaks(all_lines: list[str]) -> list[str]:
+    reflowed_lines: list[str] = []
     index = 0
-    in_fence = False
-    while index < len(lines):
-        raw = lines[index]
+    is_inside_fence = False
+    while index < len(all_lines):
+        raw = all_lines[index]
         line = raw.rstrip("\n")
         if line.lstrip().startswith("```"):
-            in_fence = not in_fence
-            output.append(line)
+            is_inside_fence = not is_inside_fence
+            reflowed_lines.append(line)
             index += 1
             continue
-        if in_fence:
-            output.append(line)
+        if is_inside_fence:
+            reflowed_lines.append(line)
             index += 1
             continue
         if line.strip() == "":
-            output.append(line)
+            reflowed_lines.append(line)
             index += 1
             continue
         buffer_line = line
         index += 1
-        while index < len(lines):
-            next_raw = lines[index].rstrip("\n")
+        while index < len(all_lines):
+            next_raw = all_lines[index].rstrip("\n")
             if next_raw.strip() == "":
                 break
             if next_raw.lstrip().startswith("```"):
@@ -154,8 +158,8 @@ def merge_soft_breaks(lines: list[str]) -> list[str]:
             else:
                 buffer_line = f"{buffer_line.rstrip()} {stripped_next}"
             index += 1
-        output.append(buffer_line)
-    return output
+        reflowed_lines.append(buffer_line)
+    return reflowed_lines
 
 
 def reflow_merged_line(line: str) -> list[str]:
@@ -212,39 +216,39 @@ def reflow_merged_line(line: str) -> list[str]:
     return wrap_paragraph_plain(stripped)
 
 
-def reflow_markdown_body(lines: list[str]) -> list[str]:
-    merged = merge_soft_breaks(lines)
-    output: list[str] = []
+def reflow_markdown_body(all_lines: list[str]) -> list[str]:
+    merged = merge_soft_breaks(all_lines)
+    reflowed_lines: list[str] = []
     for each_line in merged:
         if each_line.strip() == "":
-            output.append("")
+            reflowed_lines.append("")
             continue
-        output.extend(reflow_merged_line(each_line))
-    return output
+        reflowed_lines.extend(reflow_merged_line(each_line))
+    return reflowed_lines
 
 
-def wrap_long_bash_fence_lines(lines: list[str]) -> list[str]:
+def wrap_long_bash_fence_lines(all_lines: list[str]) -> list[str]:
     """Hard-wrap only ```bash fence bodies that still exceed MAX_WIDTH."""
-    output: list[str] = []
-    in_bash_fence = False
-    for line in lines:
-        stripped = line.lstrip()
+    wrapped_lines: list[str] = []
+    is_inside_bash_fence = False
+    for each_line in all_lines:
+        stripped = each_line.lstrip()
         if stripped.startswith("```"):
-            if not in_bash_fence:
+            if not is_inside_bash_fence:
                 lang = stripped[3:].strip().lower()
-                in_bash_fence = lang == "bash"
+                is_inside_bash_fence = lang == "bash"
             else:
-                in_bash_fence = False
-            output.append(line)
+                is_inside_bash_fence = False
+            wrapped_lines.append(each_line)
             continue
-        if in_bash_fence and len(line) > MAX_WIDTH:
-            indent_len = len(line) - len(line.lstrip())
-            indent = line[:indent_len]
-            content = line.lstrip()
+        if is_inside_bash_fence and len(each_line) > MAX_WIDTH:
+            indent_len = len(each_line) - len(each_line.lstrip())
+            indent = each_line[:indent_len]
+            content = each_line.lstrip()
             wrapped_segments: list[str] = []
             rest = content
             while len(rest) > MAX_WIDTH - len(indent):
-                room = MAX_WIDTH - len(indent) - 2
+                room = MAX_WIDTH - len(indent) - BASH_CONTINUATION_MARKER_WIDTH
                 window = rest[:room]
                 break_at = window.rfind(" ")
                 if break_at <= 0:
@@ -254,10 +258,10 @@ def wrap_long_bash_fence_lines(lines: list[str]) -> list[str]:
                 wrapped_segments.append(indent + piece + " \\")
             if rest:
                 wrapped_segments.append(indent + ("  " if wrapped_segments else "") + rest)
-            output.extend(wrapped_segments)
+            wrapped_lines.extend(wrapped_segments)
         else:
-            output.append(line)
-    return output
+            wrapped_lines.append(each_line)
+    return wrapped_lines
 
 
 def main() -> None:

package/skills/bugteam/sources.md

@@ -26,15 +26,7 @@ Direct quote:
 
 **Skill use:** Subagents return into the lead context (accumulates across loops); agent-team teammates do not pollute the lead. This skill needs the independent-context property.
 
-### Team creation in natural language
-
-Direct quote:
-
-> "tell Claude to create an agent team and describe the task and the team structure you want in natural language. Claude creates the team, spawns teammates, and coordinates work based on your prompt."
-
-**Skill use:** Maps to the `TeamCreate` tool step in the process section.
-
-### Referencing subagent types when spawning teammates
+### Referencing subagent types when spawning subagents
 
 Direct quote:
 
@@ -42,22 +34,6 @@ Direct quote:
 
 **Skill use:** Bugfind / bugfix roles reference `code-quality-agent` and `clean-coder` by subagent type name.
 
-### Lead cleanup and active teammates
-
-Direct quote:
-
-> "When the lead runs cleanup, it checks for active teammates and fails if any are still running, so shut them down first."
-
-**Skill use:** Step 4 shutdown sequence before `TeamDelete`.
-
-### Ending the team
-
-Direct quote:
-
-> "When you're done, ask the lead to clean up: 'Clean up the team'."
-
-**Skill use:** Maps to calling `TeamDelete()` after shutdown messages.
-
 ---
 
 ## Claude — Agent skills best practices

package/skills/bugteam/test_skill_additions.py

@@ -10,16 +10,9 @@ def _read_skill_text() -> str:
     return skill_path.read_text(encoding="utf-8")
 
 
-def _read_path_a_workflow_text() -> str:
-    workflow_path = (
-        pathlib.Path(__file__).parent / "reference" / "workflow-path-a-orchestrated-teams.md"
-    )
-    return workflow_path.read_text(encoding="utf-8")
-
-
 def test_skill_references_fix_implementer_env_var():
-    workflow_text = _read_path_a_workflow_text()
-    assert "BUGTEAM_FIX_IMPLEMENTER" in workflow_text
+    skill_text = _read_skill_text()
+    assert "BUGTEAM_FIX_IMPLEMENTER" in skill_text
 
 
 def test_skill_names_default_implementer_subagent_type():
@@ -28,12 +21,10 @@ def test_skill_names_default_implementer_subagent_type():
 
 
 def test_skill_names_optional_groq_implementer_subagent_type():
-    workflow_text = _read_path_a_workflow_text()
-    assert "groq-coder" in workflow_text
+    skill_text = _read_skill_text()
+    assert "groq-coder" in skill_text
 
 
 def test_skill_documents_bugbot_retrigger_flag():
     skill_text = _read_skill_text()
-    workflow_text = _read_path_a_workflow_text()
     assert "--bugbot-retrigger" in skill_text
-    assert "--bugbot-retrigger" in workflow_text

package/skills/fresh-branch/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: fresh-branch
+description: Creates a fresh branch for the current repo based on origin main. Always fetches actual origin main rather than relying on local main. Suggests possible branch names via AskUserQuestion when context is available, or prompts the user to provide a name directly. Triggers on "fresh branch", "new branch from main", "/fresh-branch", "start fresh".
+---
+
+# fresh-branch
+
+## Overview
+
+Creates a new branch from `origin/main` (always fresh-fetched, never stale local main). Designed as a shared primitive: other skills (e.g. gotcha) invoke `/fresh-branch` to create a clean branch for their own PR workflows.
+
+**Announce at start:** "Creating a fresh branch from origin/main."
+
+## Instructions
+
+### Phase 1 — Fetch origin main
+
+Always fetch `origin/main` directly. Do not rely on the local `main` branch, which may be stale.
+
+```
+git fetch origin main
+```
+
+Confirm the fetch succeeded. If it fails (no network, no remote), report the error and stop.
+
+### Phase 2 — Determine branch name
+
+Branch names follow the repo's convention: lowercase, hyphen-separated, descriptive prefix.
+
+**When context is available (the caller or prior conversation provides a topic):**
+
+Suggest 2–4 branch names via `AskUserQuestion`. The suggestions should be short, descriptive, and follow the `prefix/description` or `description` convention visible in recent `git log` output.
+
+Poll recent branch naming patterns to inform suggestions:
+
+```
+git branch -r --sort=-committerdate | head -20
+```
+
+**When no context is available:**
+
+Ask the user to provide a branch name directly via `AskUserQuestion` with `multiSelect: false` and a free-text option.
+
+### Phase 3 — Create the branch
+
+```
+git checkout -b <branch-name> origin/main
+```
+
+The `-b` flag creates the branch and checks it out. Basing on `origin/main` (not local `main`) guarantees the branch starts from the true latest state.
+
+Confirm success:
+
+```
+git rev-parse --abbrev-ref HEAD
+git log --oneline -1
+```
+
+### Phase 4 — Report
+
+State the new branch name and its base commit. If invoked as a subroutine by another skill, return the branch name so the caller can proceed (e.g., creating a PR from it).
+
+## What this skill does NOT do
+
+- Does not push the branch. The caller decides when and whether to push.
+- Does not create a PR. Use `gh pr create` separately.
+- Does not switch an existing branch. It always creates a new one.
+
+## Gotchas
+
+See the gotcha reference at the bottom of this file. When a new gotcha is discovered during use, invoke `/gotcha` to add it here.

package/skills/gotcha/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: gotcha
+description: When a skill encounters an obstacle requiring user intervention, this skill invokes bg-agent to add the gotcha to the skill file's gotcha section and creates a PR via fresh-branch. Triggers on "/gotcha", "add a gotcha", "document this gotcha", "record this obstacle".
+---
+
+# gotcha
+
+## Overview
+
+When a skill is executed and hits an obstacle that requires user intervention to resolve, `/gotcha` captures that knowledge so future invocations avoid the same trap. It delegates the mechanical work to `bg-agent`, which writes the gotcha entry and opens a PR using `fresh-branch`.
+
+**Announce at start:** "Recording this gotcha and opening a PR."
+
+## Instructions
+
+### Step 1 — Collect the gotcha
+
+The caller provides the obstacle context. Distill it into:
+
+- **Which skill file** hit the obstacle (full path, e.g. `packages/claude-dev-env/skills/rebase/SKILL.md`).
+- **What happened** — the specific failure or blocker, in one or two sentences.
+- **What the user had to do** to resolve it.
+- **What to do differently next time** (the actionable gotcha).
+
+Determine which repo the skill lives in. Usually this is `claude-code-config`, but if the skill is in another repo (e.g. a project-specific `.claude/skills/` directory), use that repo instead.
+
+### Step 2 — Delegate to bg-agent
+
+Invoke `/bg-agent` with a task like:
+
+```
+bg-agent add a gotcha to <skill-file-path> in repo <repo-name>. The gotcha is: "<one-line summary>". Details: "<what happened, what the user did, and what to do next time>."
+
+Steps:
+1. Use /fresh-branch to create a branch named gotcha/<short-slug>.
+2. In <skill-file-path>, add the gotcha entry under a ## Gotchas section (create the section at the bottom of the file if it does not exist).
+3. Format each gotcha as a bullet: "- **<title>:** <description>."
+4. Commit with message "fix(<skill-name>): add gotcha — <title>".
+5. Push and create a draft PR.
+6. Report the PR URL.
+```
+
+The bg-agent will pick a suitable agent type and run the full workflow in the background.
+
+### Step 3 — Confirm
+
+Tell the user: "Recording gotcha in the background. You will be notified when the PR is ready."
+
+## Gotcha entry format
+
+Every gotcha entry follows this format:
+
+```markdown
+## Gotchas
+
+- **<title>:** <what happens>. <what to do instead>.
+```
+
+If a `## Gotchas` section already exists, append to it. If not, create it at the bottom of the skill file.
+
+## Which repo
+
+| Skill location | Repo |
+|---|---|
+| `packages/claude-dev-env/skills/<name>/` | `jl-cmd/claude-code-config` |
+| `~/.claude/skills/<name>/` | `jl-cmd/claude-code-config` (user skills) |
+| Project `.claude/skills/<name>/` | That project's repo |
+
+When unsure, ask the user which repo. Otherwise, default to `claude-code-config`.
+
+## Gotchas
+
+- **The bg-agent prompt must be self-contained.** The background agent has no access to this conversation. Include the skill file path, the gotcha text, the repo, and the exact workflow steps in the prompt.

package/skills/monitor-open-prs/SKILL.md

@@ -7,8 +7,7 @@ description: >-
   re-trigger flag (--bugbot-retrigger), wrap the session in `bws run`
   to inject GROQ_API_KEY, and poll Cursor's bugbot replies after
   convergence so any post-Groq findings loop back through /bugteam.
-  Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Triggers:
-  '/monitor-open-prs', 'sweep the open PRs', 'groq-bugteam the backlog'.
+  Triggers: '/monitor-open-prs', 'sweep the open PRs', 'groq-bugteam the backlog'.
 ---
 
 # Monitor Open PRs
@@ -19,9 +18,8 @@ description: >-
 
 - When this skill applies — refusal cases and trigger conditions
 - Discovery — live `gh search prs` across both owner scopes
-- Team lifecycle — single long-lived team for the whole sweep
 - Wrapping — `bws run` for GROQ_API_KEY injection
-- Dispatch — `/bugteam <numbers...>` with groq-coder + retrigger
+- Dispatch — `/bugteam --bugbot-retrigger <pr_numbers...>` with groq-coder + retrigger
 - Post-convergence polling — bugbot replies and re-invocation
 - `scripts/discover_open_prs.py` — the discovery helper
 
@@ -31,7 +29,6 @@ description: >-
 
 Refusals — first match wins; respond with the quoted line exactly and stop:
 
-- **Agent teams not enabled.** Check `claude config get env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` and `~/.claude/settings.json`. If neither is `"1"`: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 not set. /monitor-open-prs requires the agent teams feature.`
 - **bws not on PATH.** `bws not installed. /monitor-open-prs injects GROQ_API_KEY via Bitwarden Secrets Manager.`
 - **gh not authenticated.** `gh auth status failed. /monitor-open-prs relies on existing gh credentials.`
 - **Dirty tree on the caller's repo.** `Uncommitted changes detected. Stash, commit, or revert before /monitor-open-prs.`
@@ -41,35 +38,6 @@ Refusals — first match wins; respond with the quoted line exactly and stop:
 
 Call `scripts/discover_open_prs.discover_open_prs(all_owners=["jl-cmd", "JonEcho"])` to merge the live open-PR list across both scopes. The helper runs `gh search prs --owner <owner> --state open --json number,repository,url,headRefName,baseRefName` once per owner and flattens the result to a uniform dict shape with keys `number`, `owner`, `repo`, `head_ref`, `base_ref`, `url`. Empty scopes contribute empty lists; an entirely empty sweep returns `[]` and exits cleanly.
 
-## Team Lifecycle
-
-`/monitor-open-prs` dispatches one `/bugteam` per discovered PR — often more than ten in a sweep. Per-invocation `TeamCreate` / `TeamDelete` from each `/bugteam` would either collide on the runtime's `Already leading team` rule or tear down the wrong team mid-sweep, depending on dispatch order. The sweep instead owns a **single long-lived team for the whole sweep** and passes that team to every `/bugteam` invocation in attach mode. See [bugteam Team lifecycle](../bugteam/SKILL.md#team-lifecycle-path-a-only).
-
-**Before the first dispatch:**
-
-1. Capture `sweep_id = <YYYYMMDDHHMMSS>` once at sweep start. This is the same convention as bugteam's team-name timestamp.
-2. Compute `team_name = "bugteam-monitor-<sweep_id>"`.
-3. `TeamCreate(team_name=<team_name>, description="monitor-open-prs sweep <sweep_id>", agent_type="team-lead")`. The orchestrator (this session) becomes the lead.
-
-**For every `/bugteam` dispatch** (parallel fan-out or serial), prepend the two attach-mode env vars to the wrapped command so bugteam reuses the orchestrator's team and skips its own `TeamCreate` / `TeamDelete`:
-
-```bash
-bws run \
-  --project-id c69cedc5-aea1-4aa8-b350-b4300145d978 \
-  -- \
-  env BUGTEAM_TEAM_LIFECYCLE=attach \
-      BUGTEAM_TEAM_NAME=<team_name> \
-      BUGTEAM_FIX_IMPLEMENTER=groq-coder \
-  /bugteam --bugbot-retrigger <pr_numbers...>
-```
-
-**Teardown — only after every PR has exited polling** (see §Post-Convergence Polling): the sweep is done; no further `/bugteam` invocation will run. At that point, and only at that point:
-
-1. `TeamDelete()` (orchestrator is the lead; no arguments).
-2. Print one cleanup line into the §Final Report: `team teardown: TeamDelete <team_name>` (success) or the error message on failure.
-
-If a hard blocker or user stop ends the sweep early, the orchestrator is shutting down: still call `TeamDelete()` once after polling stops for the in-flight PRs.
-
 ## Secret Wrapping
 
 Every `/bugteam` dispatch runs inside `bws run` so `GROQ_API_KEY` is injected from Bitwarden Secrets Manager without touching the filesystem. The project and secret UUIDs are fixed for this skill:
@@ -89,9 +57,9 @@ The `bws run` subshell resolves the project's secrets and exports them for the w
 For each discovered PR:
 
 1. Resolve the PR's repo checkout (existing worktree or fresh `git clone`).
-2. From that checkout, invoke `/bugteam <pr_number>` under the `bws run` wrapper from §Team Lifecycle (the wrapper already carries `BUGTEAM_TEAM_LIFECYCLE=attach` and `BUGTEAM_TEAM_NAME=<team_name>` so bugteam reuses the sweep-owned team).
+2. From that checkout, invoke `/bugteam --bugbot-retrigger <pr_number>` under the `bws run` wrapper from §Secret Wrapping.
 3. The `BUGTEAM_FIX_IMPLEMENTER=groq-coder` env var routes the FIX role to the `groq-coder` subagent. The `--bugbot-retrigger` flag tells bugteam to post `bugbot run` as an issue comment after every successful FIX push so Cursor's bugbot re-evaluates the new commit.
-4. Bugteam runs its own 10-loop audit/fix cycle per PR; this skill waits for each bugteam invocation to return before dispatching the next (or fanning out — see below). Each invocation skips its own `TeamCreate` / `TeamDelete` because of attach mode — only the sweep owns team teardown (§Team Lifecycle).
+4. Bugteam runs its own 10-loop audit/fix cycle per PR; this skill waits for each bugteam invocation to return before dispatching the next (or fanning out — see below).
 
 **Fan-out (optional):** when the discovered list has more than one PR, the skill may spawn `/bugteam` dispatches in parallel by issuing multiple `Agent` calls in a single assistant message. Each dispatch operates in its own per-PR worktree (bugteam Step 1.1). Serialize when the caller sets an explicit `--serial` flag.
 
@@ -127,7 +95,6 @@ Total Groq tokens consumed: <approx from /bugteam outcome summaries>
 
 ## Non-Negotiable Guardrails
 
-- Never run `/bugteam` without `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` active.
 - Never source secrets outside `bws run` — no `.env` files, no shell history, no logs.
 - Never pass `--no-verify` or `--no-gpg-sign` to git in any dispatched bugteam run.
 - Never open a PR from this skill; only comment on existing ones.

package/skills/monitor-open-prs/test_skill_contract.py

@@ -16,11 +16,6 @@ def test_skill_has_frontmatter_name():
     assert "name: monitor-open-prs" in skill_text
 
 
-def test_skill_requires_agent_teams_env_var():
-    skill_text = _read_skill_text()
-    assert "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" in skill_text
-
-
 def test_skill_invokes_bugteam_with_groq_implementer():
     skill_text = _read_skill_text()
     assert "BUGTEAM_FIX_IMPLEMENTER" in skill_text