claude-dev-env 4.3.0 → 7.0.0

package/.agents/skills/skill-builder/workflows/new-skill.md

@@ -1,179 +0,0 @@
-# New Skill Workflow
-
-Best-practice-driven lifecycle for building a skill from scratch.
-
-## Prerequisites
-
-- The user has a task or domain they want to capture as a skill
-- No existing skill for this capability (or intentionally starting fresh)
-
----
-
-## Step 1: Classify
-
-**Goal:** Determine the skill type. Type dictates folder structure.
-
-1. Read `${CLAUDE_SKILL_DIR}/references/skill-types.md`.
-
-2. Ask the user about the skill’s purpose:
-
-   > "What will this skill help Claude do?"
-
-   Match the answer against the 9 types. If ambiguous, present the top 2-3 matches and ask the user to choose.
-
-3. Record the classification: type number, type name, recommended folders.
-
-**Output:** Type classification with folder plan.
-
----
-
-## Step 2: Scaffold
-
-**Goal:** Create the folder structure. Every skill starts with the same skeleton plus type-specific additions.
-
-1. Create the skill directory if it doesn’t exist.
-
-2. Create the minimum structure:
-
-   ```
-   skill-name/
-   ├── SKILL.md          # Hub — every skill has this
-   ```
-
-3. Add type-specific directories based on Step 1 classification (see `${CLAUDE_SKILL_DIR}/references/skill-types.md` for the folder recommendations per type).
-
-4. Verify the scaffold matches the type recommendation.
-
-> "As your Skill grows, you can bundle additional content that Claude loads only when needed."
-
-**Output:** Directory tree with SKILL.md stub.
-
----
-
-## Step 3: Gather
-
-**Goal:** Collect domain knowledge, failure patterns, gotchas, and a composition plan.
-
-> "Build a Gotchas Section — these sections should be built up from common failure points that Claude runs into when using your skill."
-
-Read `${CLAUDE_SKILL_DIR}/references/skill-modularity.md`, `${CLAUDE_SKILL_DIR}/references/description-field.md`, and `${CLAUDE_SKILL_DIR}/references/deterministic-elements.md` before the interview. Modularity, description triggers, and deterministic inventory are gates: do not proceed to Write until the composition plan, trigger catalog draft, and deterministic-elements inventory are filled.
-
-### Interview questions
-
-Ask the user:
-
-1. "What task were you doing when you realized you needed a skill?"
-2. "What context did you repeatedly provide to Claude?"
-3. "Where did Claude fail or produce subpar results without guidance?"
-4. "What does Claude consistently get wrong about this domain?"
-5. "What specific format or structure do you need in the output?"
-6. "Are there rules or constraints Claude must never violate?"
-7. "What tools, scripts, or libraries does Claude need to use?"
-8. "Does this skill need to run differently for different models (Haiku vs Opus)?"
-9. "In one sentence, what is the single capability this skill owns?"
-10. "Which existing skills already cover a step of this work? Which steps should this skill invoke by name?"
-11. "Is this one skill, several skills, or a thin orchestrator that calls sub-skills?"
-12. "What exact phrases, slash commands, or file types should select this skill?"
-13. "Which steps of this work are fixed procedures (same inputs → same outputs, machine-checkable) versus open judgment?"
-
-### Related-skills inventory
-
-Scan installed skills and the package skill tree for names that touch the same domain. List each with: keep separate / invoke as sub-skill / absorb (with reason if absorb).
-
-### Generate gap analysis
-
-Use the template at `${CLAUDE_SKILL_DIR}/templates/gap-analysis.md`. Fill in:
-
-- Skill type and degree of freedom
-- Task description (one capability sentence)
-- Gaps identified (what failed, what was needed)
-- Recurring patterns across gaps
-- Initial gotcha candidates
-- **Composition plan** — capability sentence, related skills, sub-skills to invoke, split or orchestrator decision, missing sub-skills to create
-- **Description triggers** — capability stem tokens + trigger phrase list (not story prose)
-- **Deterministic elements inventory** — each process step classified; home path; paired test for code
-
-### Assess degree of freedom
-
-> "Match the level of specificity to the task’s fragility and variability."
-
-| Degree | When | Example |
-|---|---|---|
-| High | Multiple valid approaches, context-dependent | Code review guidelines |
-| Medium | Preferred pattern exists, some variation ok | Report generation with template |
-| Low | Fragile operations, consistency critical | Database migration with exact script |
-
-Record the assessment with reasoning.
-
-### Modularity gate
-
-Register each task seed from `skill-modularity.md` on the session task list (`TaskCreate` / `TodoWrite`). Complete with evidence. If the capability sentence needs an unrelated "and", stop and split scope with the user before Step 4.
-
-### Description gate
-
-Draft the frontmatter description using the template in `description-field.md`. Register each description task seed and complete with evidence. Story prose fails the gate.
-
-### Deterministic-elements gate
-
-Register each task seed under **Required task seeds** in `deterministic-elements.md`. Complete with evidence. Every deterministic step must have a planned `scripts/`, `workflow/`, `templates/`, `reference/`, or task-seed path. Prose-only mechanical sequences and markdown checkbox boards fail the gate.
-
-**Output:** Completed gap analysis (composition plan + description triggers + deterministic inventory), initial gotchas, degree-of-freedom assessment, modularity gate done, draft description.
-
----
-
-## Step 4: Write
-
-**Goal:** Produce the skill package — SKILL.md and companion files.
-
-Spawn the `skill-writer-agent` agent (`Agent(subagent_type="skill-writer-agent", ...)`) with the structured handoff from `${CLAUDE_SKILL_DIR}/references/delegation-map.md`.
-
-The handoff must include: skill type, folder structure, gap analysis (composition plan + description triggers + deterministic inventory), initial gotchas, degree of freedom, constraints, sub-skills to name in SKILL.md, exact description string to put in frontmatter, script/test paths for every deterministic step.
-
-After the `skill-writer-agent` agent produces the draft:
-
-1. Verify it follows the hub layout (principle → gotchas → when-applies → process → file index → folder map).
-2. Verify SKILL.md body is under 500 lines.
-3. Verify all references are one level deep.
-4. Verify files over 100 lines have a TOC.
-5. Verify modularity: single capability, sub-skills table when composing, no silent reimplementation of inventoried skills.
-6. Verify description is a trigger catalog per `description-field.md` (not story prose).
-7. Verify deterministic inventory: every deterministic step has a real code/artifact/task-seed path; no prose-only mechanical sequences; no markdown checkbox boards for required work; scripts follow CODE_RULES and have paired tests.
-
-Fix structural, modularity, description, and deterministic-element issues before proceeding.
-
-**Output:** Complete skill package at the target directory.
-
----
-
-## Step 5: Self-Audit
-
-**Goal:** Verify every best practice is satisfied before delivery.
-
-1. Read `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`.
-2. Register **every** bullet as a session task (`TaskCreate` / `TodoWrite`).
-3. Complete each task against the built skill: PASS, FAIL with file:line evidence, or N/A with reason.
-4. Every FAIL must be fixed before proceeding. Apply fixes, then re-open/complete that task.
-5. When all tasks are PASS or N/A, proceed to Step 6.
-
-For an independent check, spawn a subagent to run the audit (see delegation-map.md).
-
-**Output:** Audit summary (PASS / N/A / FAIL-fixed counts). All items PASS or N/A.
-
----
-
-## Step 6: Deliver
-
-**Goal:** Hand off the finished skill with full documentation. Prompt user if they want a PR up with the skill.
-
-Present to the user:
-
-1. **File map** — every file created, with its purpose.
-2. **Skill type** — classification and why it fits.
-3. **Degree of freedom** — assessment and reasoning.
-4. **Composition plan** — capability sentence, sub-skills invoked, any skills split out.
-5. **Description** — final frontmatter trigger catalog (paste the string).
-6. **Deterministic inventory** — steps classified; script/template/reference paths; tests for code.
-7. **Gotchas seeded** — initial gotchas captured.
-8. **Audit summary** — "All checklist items: N passed, M N/A."
-9. **Maintenance notes** — what to watch for in future usage that might warrant iteration.
-10. **Suggested first test** — a concrete task to try with Claude B.

package/.agents/skills/skill-builder/workflows/polish-skill.md

@@ -1,139 +0,0 @@
-# Polish Skill Workflow
-
-Final optimization pass for a skill that is functionally complete.
-
-## Prerequisites
-
-- The skill has been used and observed
-- The user is satisfied with output quality
-- This is the final step before the skill is considered done
-
----
-
-## Step 1: Description trigger-catalog audit
-
-**Goal:** Rewrite the frontmatter `description` into a dense trigger catalog. Selection metadata only — not a story.
-
-Read `${CLAUDE_SKILL_DIR}/references/description-field.md` and apply its checklist in full.
-
-> "The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills."
-
-> "The description field is not a summary — it's a description of when to trigger."
-
-### Fail conditions (must rewrite)
-
-- Multi-sentence narrative or benefits language ("helps you", "ensures reliable…")
-- First or second person
-- Process/implementation detail that belongs in the body
-- Missing concrete trigger phrases
-- Overlap with a sibling skill with no distinguishing tokens
-
-### Required shape
-
-```yaml
-description: >-
-  <capability tokens>. Triggers: <phrase>, <phrase>, <slash>, <filetype>.
-```
-
-### Description task seeds
-
-Register each as a session task; complete with evidence (no markdown checkboxes):
-
-- **Third person** — no I/you
-- **Capability stem** — what tokens, ≤20 words, no story
-- **Triggers list** — concrete phrases / slash forms / file types
-- **Under 1024 characters** (prefer much shorter; always-on context)
-- **No XML tags**
-- **Not a story** — no narrative, benefits, or process dump
-- **Sibling boundary** — distinguishable from related skills
-
-### Trigger phrase review
-
-Generate 10 variations of the user's intent:
-
-- Formal and casual phrasings
-- Cases where the user doesn't name the skill but clearly needs it
-- Cases where this skill competes with another but should win
-
-For each: would the current description select this skill?
-If you aren't sure of user's intent, present options to the user via askuserquestion for trigger phases.
-
-Also check 5 near-miss phrasings — adjacent domains that must not activate. Adjust Triggers tokens only as needed for boundary.
-
-### Fix
-
-If any check fails, rewrite. Show before/after. The after form must match `description-field.md` good examples.
-
-**Output:** Final description string (trigger catalog).
-
----
-
-## Step 2: Progressive disclosure, modularity, and deterministic audit
-
-**Goal:** Verify within-skill structure, cross-skill modularity, and deterministic placement.
-
-1. Apply hard rules in `${CLAUDE_SKILL_DIR}/references/progressive-disclosure.md`.
-2. Apply modularity rules in `${CLAUDE_SKILL_DIR}/references/skill-modularity.md`.
-3. Apply deterministic-elements rules in `${CLAUDE_SKILL_DIR}/references/deterministic-elements.md`.
-4. Cross-check matching items on `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`.
-
-### Common fixes
-
-- SKILL.md too long → move sections to companion files, leave links
-- Nested references → surface all links on SKILL.md
-- Missing TOC → add to files over 100 lines
-- Multi-capability package → split or orchestrator + named sub-skills
-- Silent reimplementation → invoke peer skill by name; add Sub-skills table
-- Mechanical sequence / fenced program / giant detector only in body → extract to `scripts/` or `workflow/`; point from process steps; add paired tests and `*_constants/` as needed
-- Verbatim templates inline → `templates/`; long fixed tables → `reference/`
-- Markdown `- [ ]` progress boards → plain task-seed list + seed instruction (`TaskCreate` / `TodoWrite`)
-
-**Output:** Verified structure, composition, and deterministic placement (and edits if needed).
-
----
-
-## Step 3: Gotcha freshness
-
-**Goal:** Ensure gotchas reflect current observations.
-
-> "Ideally, you will update your skill over time to capture these gotchas."
-
-- Review the skill's Gotchas section.
-- Check against recent usage: are there new failure modes not yet captured?
-- Remove gotchas for issues that no longer occur (the skill fixed them).
-- Verify each gotcha is actionable — a reader should know what to avoid and why.
-- Verify they are relevant by going over them 1 by 1 with the user via AskUserQuestion.
-
-**Output:** Updated gotchas section (and any new gotchas for skill-builder itself).
-
----
-
-## Step 4: Full self-audit
-
-**Goal:** Complete checklist pass including description, modularity, and deterministic items.
-
-Same as new-skill Step 5 and improve-skill Step 5:
-
-1. Read `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`.
-2. Register every bullet as a session task; complete with evidence. Fix failures. Re-complete.
-3. All items must be PASS or N/A.
-4. Description items, modularity items, and process-step classification are never N/A for a delivered skill (sub-skills table alone may be N/A for pure leaf skills; script/test rows are N/A only when the package has zero code files and every step is judgment).
-
-**Output:** Audit summary; all PASS or N/A.
-
----
-
-## Step 5: Deliver
-
-**Goal:** Final summary of the polished skill.
-
-Present to the user:
-
-1. **Description** — final trigger-catalog string (paste it).
-2. **Composition** — sub-skills or leaf status.
-3. **Deterministic inventory** — any extracts to scripts/templates/reference.
-4. **File structure** — folder map with line counts.
-5. **Gotchas** — current gotcha count and most recent additions.
-6. **Audit summary** — "All checklist items: N passed, M N/A."
-7. **Before/after** — description rewrite and structural changes if any.
-8. **Maintenance notes** — what to watch for, when to re-audit.

package/.agents/skills/source-command-sr-loop/SKILL.md

@@ -1,82 +0,0 @@
----
-name: "source-command-sr-loop"
-description: "Converging cleanup loop: repeat /simplify until clean, then repeat /code-review --fix until clean"
----
-
-# source-command-sr-loop
-
-Use this skill when the user asks to run the migrated source command `sr-loop`.
-
-## Command Template
-
-Run the converging cleanup loop on the target the user names (a PR URL,
-a branch, or blank for the current branch's diff). Each phase invokes an
-existing skill and repeats it until a pass returns zero new findings.
-
-### Nit-only terminal
-
-When a pass finds only nits, apply them, run scoped checks, commit, and push.
-Treat that phase as clean. Do not run another simplify or review pass without
-the user's request. If later work creates an uncommitted out-of-scope diff,
-stop and report it. Do not inspect, repair, commit, or adopt that diff without
-new user instruction.
-
-### Effort
-
-Set every model call to `max` effort. If that model has no `max` effort, use
-`xhigh`.
-
-### Stack context
-
-Before any fixes, load and review the full PR stack, from its base through the
-target PR. Read every PR and diff in the stack. Use that full context to judge
-each proposed simplify or code-review fix. Apply a fix only when it fits the
-stack's design, intent, and changes.
-
-### Phase A — loop simplify
-
-1. Invoke the `simplify` skill (or its local equivalent, e.g. `e-simplify`)
-   on the target. Let it run its 4-lens review fan-out (reuse,
-   simplification, efficiency, altitude) and apply its fixes.
-2. After each pass: run the scoped test suite (test files beside the touched
-   code, not the full repo suite), commit once (commit body via
-   `git commit -F <file>`, 10-minute timeout — the pre-commit gate runs its
-   own tests), and push to the PR head branch. The PR stays draft.
-3. Repeat the invocation only after substantive findings or a user request.
-   Skips are sticky: carry every adjudicated skip
-   forward into the next pass as "already adjudicated — do not re-report: ..."
-   context, or the loop never converges.
-4. Phase A converges when a full pass returns zero new findings. When the
-   previous pass changed only a line or two, a single combined-lens
-   confirmation agent may serve as the final pass.
-
-### Phase B — loop code-review with fixes
-
-1. Run the real code-review command through a headless subprocess in the
-   target worktree: `claude -p "/code-review low --fix" --max-turns 40` with a
-   10-minute timeout, reading its final text for findings and applied fixes.
-   (The skill's `disable-model-invocation` flag blocks only programmatic tool
-   starts; a `-p` prompt arrives as user input and loads normally.) Fallback
-   when the headless run fails: invoke the `e-code-review` skill with
-   `low --fix` — same review-and-fix contract, no invocation restriction.
-2. After any pass that changed files: test, commit, push as in Phase A.
-3. Repeat until a pass reports zero findings. A nit-only pass ends this phase
-   after its fixes are pushed.
-
-### Finish
-
-When both phases are clean, or only fixed nits remain, mark the target PR ready
-with `gh pr ready`. Confirm that it is no longer a draft.
-
-Report: passes run per phase, commits pushed with hashes, fixes applied, and
-the standing skip list with reasons.
-
-### Constraints (observed under headless runs)
-
-- Run this loop in the main conversation. A wrapper subagent cannot see the
-  review skills, and a nested agent's own subagent reports route to the main
-  conversation instead of back to it.
-- Scope test runs to the touched files; a full-suite run can outlive one
-  foreground tool call.
-- A hung or newly slow test suite is a finding to investigate, not an
-  inconvenience.

package/.agents/skills/update/.claude/CLAUDE.md

@@ -1 +0,0 @@
-@../AGENTS.md

package/.agents/skills/update/AGENTS.md

@@ -1 +0,0 @@
-

package/.agents/skills/update/SKILL.md

@@ -1,190 +0,0 @@
----
-name: update
-description: >-
-  Fast-forwards a local repository's main branch to a remote's main after
-  confirming the repo path and source remote through AskUserQuestion. Use when
-  the user says '/update', 'update main', 'fast-forward main', 'sync main from
-  origin', 'pull latest main into <path>', or 'bring main up to date'.
----
-
-# update
-
-## Overview
-
-Fast-forwards the local `main` branch of a given repository to a chosen remote's `main`. The move is always a true fast-forward: the skill fetches the remote, checks that local `main` is an ancestor of the remote's `main`, and advances the ref. It never forces, never creates a merge commit, and never rewrites any branch other than `main`. When `main` is not the checked-out branch, a final confirmed step offers to switch the checkout to `main` so the new commits reach the files on disk — the only branch switch the skill makes, and only after the operator approves it.
-
-The repository is whatever path the user gives as the `/update <path>` argument. With no argument, the default is the current repository's top level. Either way the path is confirmed before any write.
-
-**Announce at start:** "Confirming the repo path and source remote, then fast-forwarding main."
-
-## When this applies
-
-Trigger on a request to bring a repo's `main` up to date from a remote: "/update", "update main", "fast-forward main", "sync main from origin", "pull latest main into <path>".
-
-**Refusals — first match wins; respond with the quoted line exactly and stop:**
-
-- Path is not a git repository → `<path> is not a git repository. Give me the path to a git working tree.`
-- The chosen remote has no `main` → `<remote> has no main branch. Pick a remote whose main you want.`
-- Local `main` has diverged from the remote's `main` (not a fast-forward) → `main has diverged from <remote>/main (ahead N, behind M). A fast-forward is not possible — use /rebase or reconcile manually.`
-
-## Instructions
-
-### Phase 1 — Resolve the local path
-
-Take the path from the `/update <path>` argument. With no argument, use the current repo's top level:
-
-```
-git -C "<path>" rev-parse --show-toplevel
-```
-
-Confirm the path is a git working tree (`git -C "<path>" rev-parse --git-dir`). If not, give the first refusal line.
-
-### Phase 2 — Confirm the path and the source remote
-
-List the candidate repo's remotes and their URLs:
-
-```
-git -C "<path>" remote -v
-```
-
-Confirm both in **one** `AskUserQuestion` question — header "Target". Each choice pairs the resolved path with one remote, labelled `<path> ← <remote>/main` and described with that remote's fetch URL. Picking a choice confirms the path and the remote together.
-
-Recommend `<path> ← origin/main` first; the source-of-truth remote is not always the one named `origin`. The user picks "Other" to name a different path or remote. If they switch to a different repository, re-list its remotes and ask once more — remote names are per-repo.
-
-### Phase 3 — Fetch and fast-forward
-
-Run every command with `git -C "<path>"`. Do not `cd` into the repo.
-
-1. Fetch the chosen remote's `main`, which moves the remote-tracking ref:
-
-   ```
-   git -C "<path>" fetch <remote> main
-   ```
-
-   Stop and report on failure (no network, no remote). If the remote has no `main`, give the second refusal line.
-
-2. Read the current branch and the two commits:
-
-   ```
-   git -C "<path>" branch --show-current
-   git -C "<path>" rev-parse <remote>/main
-   git -C "<path>" rev-parse --verify main   # may not exist yet
-   ```
-
-3. Decide the case:
-
-   | Case | Condition | Action |
-   |---|---|---|
-   | Create | local `main` does not exist | `git -C "<path>" branch main <remote>/main` |
-   | Up to date | local `main` == `<remote>/main` | report, done |
-   | Diverged | `merge-base --is-ancestor main <remote>/main` is false | third refusal line, stop |
-   | Fast-forward, on main | current branch is `main` | clean check, then `merge --ff-only` |
-   | Fast-forward, off main | current branch is not `main` | `fetch <remote> main:main` |
-
-   The fast-forward gate:
-
-   ```
-   git -C "<path>" merge-base --is-ancestor main <remote>/main
-   ```
-
-   Exit 0 means a fast-forward is possible. Non-zero means diverged — refuse, never force.
-
-4. Apply the fast-forward for the matched case:
-
-   - **On `main`:** the working tree must be clean first — `git -C "<path>" status --porcelain` must be empty. If dirty, stop and report; never stash or discard. Then:
-
-     ```
-     git -C "<path>" merge --ff-only <remote>/main
-     ```
-
-   - **Off `main`:** advance the ref without touching the working tree:
-
-     ```
-     git -C "<path>" fetch <remote> main:main
-     ```
-
-     This is fast-forward-only (no leading `+`) and leaves the checked-out branch alone.
-
-### Phase 4 — Report
-
-State the old and new `main` SHAs and the one-line subject of the new tip:
-
-```
-git -C "<path>" log --oneline -1 main
-```
-
-Report the move as `main <old> → <new>`, or "already up to date" when nothing changed.
-
-Then report what the checkout runs — a move of the `main` ref says nothing about the files on disk:
-
-```
-git -C "<path>" branch --show-current
-git -C "<path>" status --short
-```
-
-- **Checked-out branch.** When a branch other than `main` is checked out, say so plainly: the fast-forward moves a ref only and no file on disk changes. Code that runs from this checkout comes from the checked-out branch, not from `main`.
-- **Dirty tracked files.** List every modified tracked file from `status --short`. Uncommitted edits sit on top of the checked-out branch and are what runs — flag them, because a ref update can neither see nor repair them. When the tree is clean, report "working tree clean".
-
-### Phase 5 — Offer to land `main` on disk
-
-A fast-forward of the `main` ref leaves the files on disk untouched when another branch is checked out. The new commits exist in the repo but not in the working tree — the gap Phase 4 reports. This phase offers to close it.
-
-Skip this phase and finish when the checked-out branch is already `main`: the new commits are already on disk.
-
-Otherwise, when the checked-out branch is not `main`, run two safety checks before offering a switch:
-
-1. **Tree clean of tracked changes.** Read `git -C "<path>" status --porcelain` and treat any line that does not start with `??` as a change to a tracked file. If any exist, do not offer the switch: report that `main` moved in the ref only, that switching would risk the uncommitted work, and stop. Never stash, reset, or discard. Untracked files (lines starting with `??`) are fine — they carry across a switch.
-2. **`main` free to check out.** Read `git -C "<path>" worktree list`. If another worktree holds `main`, an in-place switch is impossible; report that path and stop.
-
-When both checks pass, ask **one** `AskUserQuestion` — header "Get on disk":
-
-- Recommended first choice, "Switch checkout to main": `git -C "<path>" checkout main` puts the new commits on disk. The branch you were on keeps its commits and is left unchanged.
-- Second choice, "Stay on `<branch>`": leave the checkout where it is. The update stays in the `main` ref only and reaches disk later.
-
-On "Switch", run:
-
-```
-git -C "<path>" checkout main
-```
-
-If `checkout` reports it would overwrite untracked files, stop and report those paths — never pass `-f`, which would drop the operator's untracked file. On success, confirm the branch and the tip now on disk:
-
-```
-git -C "<path>" branch --show-current
-git -C "<path>" log --oneline -1
-```
-
-On "Stay", report that `main` is current in the ref and the new content reaches disk only after a later switch.
-
-## Constraints (non-negotiable)
-
-- **Fast-forward only.** If the remote's `main` is not a descendant of local `main`, stop. Never `--force`, never `branch -f`, never a merge commit. Divergence is a job for `/rebase`.
-- **Always confirm both** the path and the source remote first, even when the path is given as an argument. Skipping a confirmation is not allowed — the confirmation is the point of this skill.
-- **Switch the checkout only with approval.** The fast-forward itself touches the `main` ref alone. Switching the checked-out branch to `main` happens only in Phase 5, only after the operator approves the `AskUserQuestion`, only with a tree clean of tracked changes, and never with `-f`. The skill never switches to any branch but `main`.
-- **Never discard local work.** A dirty tree blocks the in-place fast-forward; stop and report rather than stash or reset.
-
-## Gotchas
-
-- `git fetch <remote> main:main` refuses with "Refusing to fetch into branch ... checked out" when `main` is the current branch. That is why Phase 3 branches on `git branch --show-current` and uses `merge --ff-only` when on `main`.
-- The same refusal fires when `main` is checked out in a **different worktree** of the same repo. Find it with `git -C "<path>" worktree list`, then run the fast-forward from that worktree's path, or report it and stop.
-- `<remote>/main` only moves after an explicit `git fetch`. Fetch inside every run; never compare against a remote-tracking ref left over from an earlier fetch.
-- `origin` is not always the source of truth. When a fork is `origin` and the canonical repo is another remote (often `upstream`), the confirmed remote should be the canonical one, not whichever is named `origin`.
-- Quote the path on every command — `git -C "<path>"` — so paths with spaces or a NAS drive letter survive.
-- "Up to date" describes the `main` ref, not the running code. A checkout deployed on a feature branch, or carrying uncommitted edits, runs that branch plus those edits regardless of where `main` points. Phase 4's checkout-state report exists so the operator sees that gap on every run, and Phase 5 offers to close it.
-- `git checkout main` carries untracked files across unchanged, but refuses with "untracked working tree files would be overwritten" when an untracked file sits at a path `main` tracks. Phase 5 reports those paths and stops rather than passing `-f`, which would drop the operator's untracked file.
-
-## What this skill does NOT do
-
-- Does not push, open a PR, or change any branch other than `main`.
-- Does not create feature branches, and switches only to `main` (Phase 5, with approval) — creating or switching to any other branch is `/fresh-branch`.
-- Does not reconcile a diverged `main` — that is `/rebase`.
-
-## File index
-
-| File | Purpose |
-|------|---------|
-| `SKILL.md` | This hub — the complete skill. |
-
-## Folder map
-
-- `SKILL.md` — the whole skill. Flat by design: the operation is a short, deterministic git sequence with no scripts or reference files to load.

package/_shared/pr-loop/AGENTS.md

@@ -1 +0,0 @@
-

package/_shared/pr-loop/CLAUDE.md

@@ -1 +0,0 @@
-@AGENTS.md