claude-dev-env 1.93.1 → 1.95.0

package/skills/fixbugs/SKILL.md

@@ -1,142 +0,0 @@
----
-name: fixbugs
-description: >-
-  Fixes the bugs from the latest /findbugs run by handing them to /agent-prompt,
-  which spawns a background agent to apply every fix in one commit. An optional
-  argument filters by severity (e.g. /fixbugs P0). Triggers: '/fixbugs', 'fix
-  all the bugs', 'apply the audit fixes', 'apply the findbugs results'.
----
-
-# Fixbugs
-
-**Core principle:** A thin bridge between `/findbugs` (read-only audit) and `/agent-prompt` (structured prompt authoring + spawn). /fixbugs recovers the prior findings, packages them as a goal, and hands off. It does not author prompts itself, does not spawn agents directly, and does not run audits.
-
-## Transport check (before any GitHub step)
-
-Run `command -v gh`; when it succeeds, run `gh auth status`; once the PR scope is resolved, run `gh api repos/<owner>/<repo> --jq .permissions.push` and take `true` as the pass. When any check fails, run the `pr-loop-cloud-transport` skill first, route every `gh` operation in this skill through its substitution matrix, and carry the same routing into the goal string handed to `/agent-prompt` so the spawned fix agent inherits it.
-
-## When this skill applies
-
-Right after `/findbugs` returned findings on the current branch and the user wants the bugs fixed without further triage. Bare `/fixbugs` defaults to all severities (P0 + P1 + P2). Argument-filtered invocations (e.g. `/fixbugs P0`, `/fixbugs P0+P1`, `/fixbugs P0 P1`) narrow the target set.
-
-Refusal cases:
-
-- **No findings in session.** Respond exactly: `No findings in this session. Run /findbugs first.` and stop.
-- **Most recent /findbugs returned zero bugs.** Respond exactly: `No bugs to fix.` and stop.
-- **Filter excludes every finding.** Respond: `No bugs match the filter <args>.` and stop.
-- **Agent-prompt skill not installed.** Before Step 1, verify the `agent-prompt` skill is in the available skills list. If missing, respond: `agent-prompt skill not installed. /fixbugs hands off to it; install it first.` and stop.
-
-## The Process
-
-### Step 1: Recover the findings
-
-Locate the most recent `/findbugs` output in the current conversation. For each finding, capture:
-
-- Severity (`P0` / `P1` / `P2`)
-- `file:line`
-- Category (the A–P letter or category name `/findbugs` reported)
-- One-sentence description as `/findbugs` wrote it
-
-Apply the severity filter from `$ARGUMENTS` if present:
-
-- `P0` → P0 only
-- `P0+P1` or `P0 P1` → P0 and P1
-- `P1` → P1 only
-- absent → all severities
-
-If the filtered set is empty, refuse per the refusal cases above.
-
-### Step 2: Re-resolve PR scope
-
-Apply the `pr-scope-resolve` skill (`../pr-scope-resolve/SKILL.md`) with caller `fixbugs` to resolve the same PR target `/findbugs` used — the fixes stay scoped to the files the `/findbugs` findings from Step 1 name. When no target exists, respond with the sub-skill's canonical refusal line and stop:
-
-`No PR or upstream diff. /fixbugs needs a target.`
-
-Capture: `<owner>/<repo>`, head branch, base branch, PR number, PR URL.
-
-### Step 3: Hand off to /agent-prompt
-
-Invoke the `agent-prompt` skill with a goal string of this exact shape:
-
-```
-Fix the following bugs surfaced by /findbugs on
-<owner>/<repo> @ <head_branch> (PR #<number>, base <base_branch>):
-
-[for each filtered finding, one bullet:]
-- [<severity>] <file:line> (<category>): <description>
-
-Deploy a background implementer (model: sonnet) to implement all fixes
-in one commit on the existing branch and push. The implementer must **Read** the clean-coder agent file first (`~/.claude/agents/clean-coder.md`; Windows `%USERPROFILE%\.claude\agents\clean-coder.md`) and treat it as binding; on Cursor use `Task` + `generalPurpose` with that Read in the prompt when `clean-coder` is not a valid `Task` subtype. Constraints:
-- Modify only the files referenced in the bug list above.
-- Do NOT change the PR base, do NOT rebase, do NOT amend, do NOT --force.
-- Do NOT skip git hooks (no --no-verify, no --no-gpg-sign).
-- Use git add by explicit path; never `git add .` or `git add -A`.
-- Preserve existing comments on lines you do not modify.
-- Type hints on every signature you touch.
-
-After push, report: commit SHA, per-file lines added/removed, hook output
-summary, and confirmation that each bug above was addressed.
-```
-
-`/agent-prompt` then runs its own workflow end-to-end: prompt-generator authoring, Outcome preview, AskUserQuestion confirmation gate, background spawn. The confirmation gate is preserved — fixes are write operations and the user must approve the final XML before the agent runs.
-
-### Step 4: Hand-off complete
-
-`/fixbugs` produces no further output. `/agent-prompt` owns the visible chat from this point: the XML fence, the Outcome digest, the AskUserQuestion, and the spawn confirmation. Do not duplicate any of those, do not summarize them, do not add commentary.
-
-## Output Format
-
-When `/fixbugs` proceeds, the visible output is `/agent-prompt`'s output — nothing from `/fixbugs` itself.
-
-When `/fixbugs` short-circuits (no findings, no PR, empty filter, zero bugs), the visible output is the single-line refusal message and nothing else.
-
-## Constraints
-
-- **Sequencing.** `/fixbugs` runs AFTER `/findbugs`. It does not perform audits.
-- **Scope inheritance.** Fixes target only files referenced in the prior `/findbugs` findings — the PR diff scope. Do not expand to unrelated files.
-- **No silent spawn.** `/agent-prompt`'s confirmation gate is preserved on every run.
-- **One commit per `/fixbugs` run.** All filtered fixes batch into a single commit.
-- **No `--force`, no `--amend`, no rebase, no base change.** Standard git workflow applies to the spawned agent.
-- **Sonnet for the implementer.** Always pass `model: sonnet` to the spawn — keeps cost predictable and matches the agent's training fit for code edits.
-- **Background spawn.** The user typed `/fixbugs` to delegate, not to wait. The agent runs in the background and notifies on completion.
-
-## Examples
-
-<example>
-User: `/findbugs` → returns `1 P0 / 2 P1 / 0 P2`
-User: `/fixbugs`
-Claude: [recovers all 3 findings, resolves PR scope, invokes /agent-prompt with a goal targeting all 3 bugs; /agent-prompt presents the XML + Outcome digest + AskUserQuestion; on Launch it, the background sonnet implementer spawns]
-</example>
-
-<example>
-User: `/findbugs` → returns `1 P0 / 2 P1 / 1 P2`
-User: `/fixbugs P0+P1`
-Claude: [filters to 3 findings (the P2 is dropped), hands the filtered set to /agent-prompt]
-</example>
-
-<example>
-User: `/fixbugs` (no prior /findbugs in session)
-Claude: `No findings in this session. Run /findbugs first.`
-</example>
-
-<example>
-User: `/findbugs` → returns `0 P0 / 0 P1 / 0 P2`
-User: `/fixbugs`
-Claude: `No bugs to fix.`
-</example>
-
-<example>
-User: `/findbugs` → returns `0 P0 / 0 P1 / 1 P2`
-User: `/fixbugs P0`
-Claude: `No bugs match the filter P0.`
-</example>
-
-## Why this design
-
-Three skills, three responsibilities:
-
-- `/findbugs` audits in a clean room, returns findings.
-- `/fixbugs` packages findings as a goal, delegates.
-- `/agent-prompt` authors the XML and spawns the agent (with confirmation).
-
-Each skill stays small and reuses what already exists. `/fixbugs` adds value by recovering findings from chat, filtering by severity, and writing the goal in `/agent-prompt`'s expected shape — not by reimplementing prompt authoring or spawn logic. The `/agent-prompt` confirmation gate is non-negotiable because fixes write code, push to a PR, and are visible to reviewers; the friction is the safety.

package/skills/gh-paginate/CLAUDE.md

@@ -1,18 +0,0 @@
-# gh-paginate skill
-
-Provides the safe-pagination rule and patterns for `gh api` calls against paginated GitHub list endpoints (PR reviews, PR comments, issue comments, pulls, issues). The rule prevents two silent-truncation defects: default page truncation and per-page `--jq` evaluation.
-
-**Trigger:** Loaded by the `gh-paginate` skill name or when any skill or rule references the pagination rule.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | The complete rule: affected endpoints, safe `--paginate --slurp \| jq` pattern, single-page bound pattern, single-object pattern, newest-first walk pattern, and enforcement notes |
-
-## Conventions
-
-- The preferred pattern pipes `--paginate --slurp` to an **external** `jq` invocation so cross-page operations (`sort_by`, `last`, `reverse`) run on the merged array-of-pages. The built-in `--jq` flag is incompatible with `--slurp` and runs per-page, producing wrong cross-page results.
-- Single-object endpoints (e.g., `pulls/<number>`) are not paginated; `--paginate` is unnecessary and `gh --jq` is safe.
-- The single-page bound pattern (`?per_page=100` without `--paginate`) is acceptable only when the list is confirmed to stay under 100 entries.
-- This skill ships as documentation only; enforcement via a future PreToolUse hook is noted in `SKILL.md`.

package/skills/gh-paginate/SKILL.md

@@ -1,84 +0,0 @@
----
-name: gh-paginate
-description: Safe pagination for gh api reads of paginated GitHub list endpoints (PR reviews/comments/files, issue comments, pulls, issues) — --paginate --slurp piped to external jq, single-page bounds, newest-first walks. Use before composing any gh api list-endpoint call or any cross-page jq operation (sort_by | last, reverse).
----
-
-# gh API Pagination Rule
-
-**Root cause:** GitHub REST API list endpoints paginate by default. Without `--paginate --slurp`, callers see only the oldest page, and cross-page jq operations (e.g., `sort_by | last`) operate within a single page — producing wrong-but-confident results.
-
-**Rule:** All `gh api` calls that read `pulls/<number>/reviews`, `pulls/<number>/comments`, `issues/<number>/comments`, or any other paginated GitHub list endpoint **must** request the full set of pages AND apply any cross-page jq operation through external `jq`, not through `gh`'s built-in `--jq`. Use `--paginate --slurp | jq` (preferred — see [Safe patterns](#safe-patterns)). Never call these endpoints with their default pagination, and never use `gh`'s `--jq` for cross-page operations like `sort_by | last` or `| reverse | .[0]`.
-
-## Two defects, one rule
-
-This rule guards against two distinct silent-truncation defects that compound:
-
-1. **Default page truncation.** Without `--paginate`, only the first page is fetched.
-2. **`--jq` runs per-page, not on the concatenated result.** Per [GitHub CLI #10459](https://github.com/cli/cli/issues/10459), `gh api --paginate --jq '<filter>'` applies `<filter>` to each page **separately** and emits one output per page. Cross-page operations like `sort_by(.submitted_at) | last` therefore operate within each page independently, not across the merged result set.
-
-The safe patterns below fix both defects together: `--paginate --slurp` walks every page AND emits a single merged structure, and an **external** `jq` then runs cross-page operations on that merged structure.
-
-## Affected endpoints
-
-The rule applies to every paginated read from the GitHub REST API. Common offenders in PR-loop skills:
-
-- `gh api repos/<owner>/<repo>/pulls/<number>/reviews`
-- `gh api repos/<owner>/<repo>/pulls/<number>/comments`
-- `gh api repos/<owner>/<repo>/pulls/<number>/files`
-- `gh api repos/<owner>/<repo>/issues/<number>/comments`
-- `gh api repos/<owner>/<repo>/pulls`
-- `gh api repos/<owner>/<repo>/issues`
-
-The same rule applies to any other endpoint documented as paginated by GitHub (see [GitHub REST API pagination](https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api)).
-
-Single-object endpoints (e.g., `repos/<owner>/<repo>/pulls/<number>` returning one PR object) are not paginated — `?per_page=...` is silently ignored, and neither `--paginate` nor external `jq` is required. Use `gh`'s `--jq` directly on those endpoints.
-
-## Safe patterns
-
-### Preferred — `--paginate --slurp` piped to external `jq`
-
-`gh api ... --paginate --slurp` walks every page and emits a single merged JSON array of page-arrays (`[[page1_items...], [page2_items...], ...]`). Pipe to external `jq` to flatten and filter across the full result set:
-
-```bash
-gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' --paginate --slurp \
-  | jq '[.[][] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
-```
-
-The `.[][]` flattens the array-of-pages into one stream of items before the cross-page operators (`sort_by`, `last`, `reverse`) run. Combine with `?per_page=100` to reduce round-trips on long PRs.
-
-`gh`'s `--jq` flag and `--slurp` flag are mutually exclusive (gh CLI rejects `--paginate --slurp --jq` with `the --slurp option is not supported with --jq or --template`), which is why the filter must run in an external `jq` invocation.
-
-### Acceptable — single-page bound on a paginated list endpoint when result fits
-
-When you have an explicit reason to read at most one page from a **paginated** list endpoint (e.g., a known-small list), document the bound in a comment and use `?per_page=100` without `--paginate`. Cross-page operators are not in play here, so `gh`'s `--jq` is safe:
-
-```bash
-# Bound: a freshly created issue is expected to have <= 100 comments.
-gh api 'repos/<owner>/<repo>/issues/<number>/comments?per_page=100' \
-  --jq '[.[] | select(.user.login=="cursor[bot]")] | length'
-```
-
-This pattern is only safe when the endpoint is confirmed to return a list smaller than 100 entries. Lists that grow over the PR's lifetime (reviews, comments) must use `--paginate --slurp` plus external `jq`.
-
-### Single-object endpoints — no pagination needed
-
-Endpoints that return a single object (e.g., `pulls/<number>`, `issues/<number>`) are not paginated. `?per_page=...`, `--paginate`, and `--slurp` are all unnecessary. Use `gh`'s built-in `--jq` directly:
-
-```bash
-gh api 'repos/<owner>/<repo>/pulls/<number>' --jq '.head.sha'
-```
-
-### Newest-first walk
-
-Pair pagination with explicit reverse-sort so the consumer reads newest-first regardless of the API's internal order:
-
-```bash
-gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' --paginate --slurp \
-  | jq '[.[][] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | reverse'
-```
-
-This is the canonical pattern for the bugbot <-> bugteam convergence loop: walk newest-first, stop at the first clean review.
-
-## Enforcement
-
-This rule is documentation-only at present. A future PreToolUse hook may pattern-match `Bash` invocations of `gh api repos/.../pulls/<n>/(reviews|comments)` without `--paginate --slurp` (or with `--paginate --jq` doing cross-page operations) and return a corrective message. Until that hook lands, treat this rule as binding by review and rely on it during skill authoring.

package/skills/gotcha/CLAUDE.md

@@ -1,33 +0,0 @@
-# gotcha skill
-
-Captures an obstacle encountered during a skill run and records it as a gotcha entry in the relevant skill file, then opens a draft PR via the `fresh-branch` skill.
-
-**Trigger:** `/gotcha`, "add a gotcha", "document this gotcha", "record this obstacle".
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Full workflow: collect obstacle details, delegate to `bg-agent`, confirm to user |
-
-## Workflow
-
-1. Distill the obstacle into: which skill file was affected, what happened, what the user did to resolve it, and what to do differently next time.
-2. Invoke `/bg-agent` with a self-contained prompt that instructs the agent to use `/fresh-branch` (branch name `gotcha/<short-slug>`), append to or create a `## Gotchas` section at the bottom of the skill file, commit, push, and open a draft PR.
-3. Confirm to the user that the recording is running in the background.
-
-## Gotcha entry format
-
-Each entry is a bullet under `## Gotchas`:
-
-```markdown
-- **<title>:** <what happens>. <what to do instead>.
-```
-
-## Repo routing
-
-| Skill location | Target repo |
-|---|---|
-| `packages/claude-dev-env/skills/<name>/` | `jl-cmd/claude-dev-env` |
-| `~/.claude/skills/<name>/` | `jl-cmd/claude-dev-env` |
-| Project `.claude/skills/<name>/` | That project's repo |

package/skills/gotcha/SKILL.md

@@ -1,73 +0,0 @@
----
-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-dev-env`, 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-dev-env` |
-| `~/.claude/skills/<name>/` | `jl-cmd/claude-dev-env` (user skills) |
-| Project `.claude/skills/<name>/` | That project's repo |
-
-When unsure, ask the user which repo. Otherwise, default to `claude-dev-env`.
-
-## 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/implement/CLAUDE.md

@@ -1,27 +0,0 @@
-# Spec Execution Skill
-
-This skill (`implement`) runs a spec end-to-end while maintaining a sidecar `implementation-notes.html` that records design decisions, deviations, tradeoffs, and open questions made during the build.
-
-**Trigger:** `/implement [path-to-spec]`, "build out this plan and keep notes".
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Full workflow: resolve spec, run it, write notes via `append_note.py` |
-| `packages/claude-dev-env/skills/implement/scripts/append_note.py` | CLI that creates or appends to `implementation-notes.html` |
-| `packages/claude-dev-env/skills/implement/scripts/implement_scripts_constants/notes_constants.py` | Section slugs → headings and default filename |
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `scripts/` | Python CLI and constants for the notes file |
-
-## Conventions
-
-- The spec is taken from `$ARGUMENTS` (path) or the most recent plan in conversation context. If neither is present, the skill asks via `AskUserQuestion`.
-- Notes are appended as decisions are made — not batched at the end.
-- The `append_note.py` CLI accepts `--section decisions|deviations|tradeoffs|questions`, `--about`, `--note`, and optionally `--file`. When `--file` is omitted, the script writes to `./implementation-notes.html`.
-- `$CLAUDE_SKILL_DIR` is substituted by Claude Code at runtime so the bundled script is found regardless of the current working directory.
-- The notes file structure must not be hand-edited — `append_note.py` locates sections by `<section id="...">` markers and the first `</ul>` after each.

package/skills/implement/SKILL.md

@@ -1,66 +0,0 @@
----
-name: implement
-description: "Implement a spec while maintaining a running implementation-notes.html file that captures design decisions, deviations, tradeoffs, and open questions. Triggers: /implement, implement this spec, build out this plan and keep notes."
-argument-hint: "[path to spec file, or omit to use a spec already in context]"
----
-
-# implement
-
-Execute a spec end-to-end while keeping a sidecar `implementation-notes.html` that the user can read to see how the build diverged from or interpreted the written plan.
-
-## Instructions
-
-Carry out the following prompt against the spec resolved below.
-
-### Resolve `<SPEC>`
-
-- If `$ARGUMENTS` is non-empty, treat it as the path to the spec file and read it.
-- Otherwise, use the most recent plan / spec / design doc already present in the conversation context.
-- If neither is available, ask the user for the spec path via `AskUserQuestion` before proceeding.
-
-### Prompt to execute
-
-> Implement `<SPEC>`. As you work maintain a running `implementation-notes.html` file that captures anything I should know about how the implementation diverges from or interprets the spec, including:
->
-> - **Design decisions:** choices you made where the spec was ambiguous
-> - **Deviations:** places where you intentionally departed from the spec, and why
-> - **Tradeoffs:** alternatives you considered and why you picked what you did
-> - **Open questions:** anything you'd want me to confirm or revise
-
-### How to write notes
-
-Run `${CLAUDE_SKILL_DIR}/scripts/append_note.py` to append each entry. The script creates `implementation-notes.html` with the four sections on first run, then inserts a new `<li>` under the requested section. HTML-escapes `--about` and `--note` automatically. `${CLAUDE_SKILL_DIR}` is host-substituted by Claude Code at runtime so the bundled CLI is found regardless of the current working directory.
-
-```
-python "${CLAUDE_SKILL_DIR}/scripts/append_note.py" \
-  --section decisions \
-  --about "Storage location" \
-  --note "Wrote notes next to the spec because the spec path was provided." \
-  --file /path/to/spec-dir/implementation-notes.html
-```
-
-`--section` choices (slug → heading):
-
-| Slug | Heading |
-|---|---|
-| `decisions` | Design decisions |
-| `deviations` | Deviations |
-| `tradeoffs` | Tradeoffs |
-| `questions` | Open questions |
-
-`--file` is optional. When omitted, the script writes to `./implementation-notes.html` in the current working directory. When a spec path is known, pass `--file` so notes land next to the spec rather than in CWD.
-
-Append entries as decisions are made — do not batch them until the end.
-
-## Gotchas
-
-- **Do not hand-edit `implementation-notes.html`.** The append script locates each section by its `<section id="...">` marker and the first `</ul>` after it. Editing the structure breaks subsequent appends; the script raises a `RuntimeError` naming the missing marker.
-- **`--about` and `--note` are HTML-escaped automatically** — pass raw text, not pre-escaped HTML.
-
-## File index
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | This hub |
-| `packages/claude-dev-env/skills/implement/scripts/append_note.py` | CLI to append one entry to a section |
-| `packages/claude-dev-env/skills/implement/scripts/implement_scripts_constants/notes_constants.py` | Section slugs → headings and default filename |

package/skills/implement/scripts/CLAUDE.md

@@ -1,22 +0,0 @@
-# scripts (spec-build skill)
-
-Support scripts for the spec-build (`implement`) skill. These scripts create and append to the `implementation-notes.html` sidecar file the skill maintains during a spec build.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `append_note.py` | CLI that creates `implementation-notes.html` with four sections on first run and appends a `<li>` to a named section on later runs |
-| `test_append_note.py` | Tests for `append_note.py` |
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `implement_scripts_constants/` | Section slug → heading map and default filename constant |
-
-## Conventions
-
-- `append_note.py` imports section metadata from `implement_scripts_constants.notes_constants`.
-- HTML-escaping of `--about` and `--note` is handled by the script; callers pass raw text.
-- The script is invoked as `python "${CLAUDE_SKILL_DIR}/scripts/append_note.py"` from within the skill, where `$CLAUDE_SKILL_DIR` resolves to the installed skill directory at runtime.

package/skills/implement/scripts/append_note.py

@@ -1,133 +0,0 @@
-#!/usr/bin/env python3
-"""Append an entry to implementation-notes.html under one of four sections.
-
-Used by the `implement` skill. Creates the file with all four sections if it
-does not exist; otherwise appends a new <li> under the requested section.
-
-Usage:
-    python append_note.py --section decisions --about "Where to write the file" --note "Wrote next to spec rather than CWD because spec path was known."
-    python append_note.py --section questions --about "Auth model" --note "Spec didn't say whether sessions persist across restarts." --file ./notes.html
-"""
-
-from __future__ import annotations
-
-import argparse
-import html
-import sys
-from pathlib import Path
-
-from implement_scripts_constants.notes_constants import DEFAULT_NOTES_FILENAME, HEADING_BY_SLUG
-
-
-def _build_skeleton() -> str:
-    section_blocks = "\n".join(
-        f'  <section id="{each_slug}">\n    <h2>{each_heading}</h2>\n    <ul></ul>\n  </section>'
-        for each_slug, each_heading in HEADING_BY_SLUG.items()
-    )
-    return (
-        "<!doctype html>\n"
-        '<html lang="en">\n'
-        "<head>\n"
-        '  <meta charset="utf-8">\n'
-        "  <title>Implementation notes</title>\n"
-        "</head>\n"
-        "<body>\n"
-        "  <h1>Implementation notes</h1>\n"
-        f"{section_blocks}\n"
-        "</body>\n"
-        "</html>\n"
-    )
-
-
-def _ensure_file(target: Path) -> str:
-    if not target.exists():
-        target.parent.mkdir(parents=True, exist_ok=True)
-        skeleton = _build_skeleton()
-        target.write_text(skeleton, encoding="utf-8")
-        return skeleton
-    return target.read_text(encoding="utf-8")
-
-
-def _render_entry(about: str, note: str) -> str:
-    return f"<li><strong>{html.escape(about)}:</strong> {html.escape(note)}</li>"
-
-
-def _insert_entry(document: str, slug: str, entry: str) -> str:
-    open_marker = f'<section id="{slug}">'
-    section_close_marker = "</section>"
-    close_marker = "</ul>"
-    section_start = document.find(open_marker)
-    if section_start == -1:
-        raise RuntimeError(
-            f"section '{slug}' not found in file — the file may have been "
-            f"edited by hand. Restore the four <section id=...> blocks or "
-            f"delete the file so it can be regenerated."
-        )
-    section_end = document.find(section_close_marker, section_start)
-    if section_end == -1:
-        raise RuntimeError(
-            f"section '{slug}' is missing its closing </section> — the file "
-            f"may have been edited by hand."
-        )
-    close_at = document.find(close_marker, section_start, section_end)
-    if close_at == -1:
-        raise RuntimeError(
-            f"section '{slug}' is missing its closing </ul> — the file may "
-            f"have been edited by hand."
-        )
-    boundary = close_at
-    while boundary > 0 and document[boundary - 1] in (" ", "\n"):
-        boundary -= 1
-    new_line = f"\n      {entry}"
-    return document[:boundary] + new_line + "\n    " + document[close_at:]
-
-
-def _parse_arguments() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        description=f"Append an entry to {DEFAULT_NOTES_FILENAME}.",
-    )
-    parser.add_argument(
-        "--section",
-        required=True,
-        choices=sorted(HEADING_BY_SLUG.keys()),
-        help="Which section to append under.",
-    )
-    parser.add_argument(
-        "--about",
-        required=True,
-        help="Short label naming the part of the spec this entry relates to.",
-    )
-    parser.add_argument(
-        "--note",
-        required=True,
-        help="The decision / deviation / tradeoff / question itself.",
-    )
-    parser.add_argument(
-        "--file",
-        default=DEFAULT_NOTES_FILENAME,
-        help=(
-            f"Path to the notes file. Defaults to ./{DEFAULT_NOTES_FILENAME} "
-            f"in the current working directory."
-        ),
-    )
-    return parser.parse_args()
-
-
-def main() -> int:
-    """Parse CLI arguments and append one entry to the notes file.
-
-    Returns:
-        Process exit code (0 on success).
-    """
-    arguments = _parse_arguments()
-    target_path = Path(arguments.file).expanduser().resolve()
-    document = _ensure_file(target_path)
-    entry = _render_entry(arguments.about, arguments.note)
-    updated = _insert_entry(document, arguments.section, entry)
-    target_path.write_text(updated, encoding="utf-8")
-    print(f"appended to [{arguments.section}] in {target_path}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/skills/implement/scripts/implement_scripts_constants/CLAUDE.md

@@ -1,22 +0,0 @@
-# implement_scripts_constants
-
-Constants module for the `implement` skill's `append_note.py` script.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `__init__.py` | Package marker |
-| `notes_constants.py` | `HEADING_BY_SLUG` dict (section slugs → display headings) and `DEFAULT_NOTES_FILENAME` |
-
-## Exported constants
-
-| Constant | Value | Used by |
-|---|---|---|
-| `HEADING_BY_SLUG` | `{"decisions": "Design decisions", "deviations": "Deviations", "tradeoffs": "Tradeoffs", "questions": "Open questions"}` | `append_note.py` — maps `--section` slug to the `<h2>` heading in the HTML file |
-| `DEFAULT_NOTES_FILENAME` | `"implementation-notes.html"` | `append_note.py` — default output path when `--file` is omitted |
-
-## Conventions
-
-- This module is imported directly by `append_note.py` in the parent `scripts/` directory.
-- Adding a new section requires a new entry in `HEADING_BY_SLUG` and a matching branch in `append_note.py`.

package/skills/implement/scripts/implement_scripts_constants/notes_constants.py

@@ -1,12 +0,0 @@
-"""Configuration for the implementation-notes append script."""
-
-from __future__ import annotations
-
-HEADING_BY_SLUG: dict[str, str] = {
-    "decisions": "Design decisions",
-    "deviations": "Deviations",
-    "tradeoffs": "Tradeoffs",
-    "questions": "Open questions",
-}
-
-DEFAULT_NOTES_FILENAME = "implementation-notes.html"