@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/worktrees/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: worktrees
+description: "Use when work is about to become commits and needs isolation first — check the tree state, then branch or cut a git worktree off a clean base (native EnterWorktree first, git fallback) so implement never runs on main. NOT what may run concurrently inside those workspaces (that is `parallel`), NOT the merge/cleanup after (that is `ship`)."
+tags: [git, worktree, isolation]
+recommends: []
+profiles: [core, full]
+origin: ai-hub
+---
+
+# worktrees — isolate the work before you touch it
+
+Before you execute a plan you guarantee one thing: **the work happens somewhere that can be thrown
+away without harming the main checkout.** A feature branch keeps history clean; a *worktree* goes
+further — a second working directory on its own branch, so you can build, run, and test the feature
+without disturbing the files you (or another agent, or a running dev server) have open on the
+default branch.
+
+`worktrees` is an **on-demand** step in the SDD chain — not a numbered phase, but the gate that
+`implement` calls when it finds itself on `main`. It does exactly one job: confirm an isolated
+workspace exists, create one if it doesn't, and hand back. It writes no runtime code and leaves no
+artifact under `02-DOCS`; isolation is plumbing, not knowledge.
+
+```text
+constitution → specify → clarify → plan → tasks → analyze → [ worktrees ] → implement → verify → review → ship
+                                                              on-demand, called before the first commit
+```
+
+## The one rule that defines this step
+
+**Never open a branch on your own; follow the project's decision.** Where the default branch is open
+(chosen at install, or nothing complex), `implement` runs on it. Where it is closed («ramas y PR»,
+CI, team), stop before the first edit and ask «¿esta rama, una nueva, o desbloqueo `main`?» — not
+after the diff already exists. The one exception is another session in this folder: then the
+worktree is mandatory, not a question.
+
+## The decision: branch vs. worktree
+
+Both isolate history. A worktree also isolates the *filesystem*. Pick by what's actually in play.
+
+| Situation | Use | Why |
+| --- | --- | --- |
+| Solo, single task, clean tree, no parallel work | **branch** (`git switch -c`) | Cheapest isolation; nothing else needs the main checkout right now. |
+| A dev server, build watcher, or editor is live on the current files | **worktree** | A branch switch yanks files out from under the running process; a worktree leaves them put. |
+| You'll run two streams of work at once (see the parallel pattern) | **worktree** | Each stream gets its own directory; no stash-juggling, no checkout thrash. |
+| The current tree is dirty and the user wants both the WIP and the new work | **worktree** | Stash-and-switch risks losing the WIP; a worktree sidesteps the stash entirely. |
+| You're an agent that may keep the main session running elsewhere | **worktree** | Filesystem isolation is the whole point — the parent session keeps its files. |
+| **Another session is working in this same folder** (ai-hub says so on each message) | **worktree — mandatory** | Switching branches would change its files under it; ai-hub's branch guard denies the switch. Tell the person that `.worktrees/<branch>/` is where the project now runs. Off for the project: `npx ai-hub isolation off`. |
+
+When in doubt, prefer a **worktree**: it is the strictly stronger isolation and the cost is one
+extra directory. The rest of this skill assumes a worktree; the branch path is the degenerate case
+(skip the directory, keep the branch).
+
+## Before you create anything — the pre-flight gate
+
+Run this in order. Each check prevents a class of "lost work" you can't easily undo.
+
+1. **Read the register** — `technical_level` in `02-DOCS/wiki/harness/user-profile.md` picks
+   technical terms or plain words with analogies (see "Talking about it" below). No profile yet, or
+   no `02-DOCS/` at all (a worktree can be created in any git repo with no ai-hub harness present) →
+   use analogies: explain what a worktree is in one plain sentence before making one, and proceed.
+2. **Confirm you're in a git repo.** `git rev-parse --is-inside-work-tree`. If not, there's nothing
+   to isolate with git — tell the user; don't fabricate a worktree.
+3. **Check the current branch.** `git rev-parse --abbrev-ref HEAD`. On `main`/`master` with work
+   about to start → this skill is exactly right. Already on a feature branch with a clean tree →
+   isolation may already be sufficient; say so and don't create a redundant one.
+4. **Check the tree state.** `git status --short`. A **dirty tree is a fork in the road**, not a
+   thing to bulldoze:
+   - Uncommitted changes that belong to the *new* feature → a worktree built from a clean base means
+     those changes stay on the old branch. Surface this; ask whether to commit/stash them first or
+     carry them over. Never silently leave a user's WIP behind.
+   - Unrelated WIP → that's the textbook reason to use a worktree (isolate the new work, leave the
+     WIP exactly where it sits).
+   - A dirty tree you don't understand is a hard stop: surface every modified path and ask before
+     branching or stashing. Lost WIP is the one unrecoverable failure in this step.
+5. **Pick the base ref.** Branch from an up-to-date default branch unless the user wants to build on
+   local HEAD. Stale base = predictable merge pain later. Default: fresh from `origin/<default>`.
+6. **Choose a name** tied to the feature slug — the same `<slug>` the spec and plan use
+   (`feat/<slug>`), so the branch, the spec at `02-DOCS/wiki/sdd/specs/<slug>.md`, and the plan at
+   `02-DOCS/wiki/sdd/plans/<slug>.md` all line up and are trivially traceable. A change that is not
+   a feature takes the type that fits — `fix/<slug>`, `docs/<slug>`, `chore/<slug>` — from the same
+   Conventional Commits vocabulary the commit guard already enforces here. **The prefix is load
+   bearing**: the automatic cleanup uses it, with the location, as the two signals that say a
+   worktree is ours to remove. A name outside that vocabulary is never swept for you.
+
+Only once the tree state is understood and the user's WIP is accounted for do you create anything.
+
+## Creating the workspace — native first, git fallback
+
+**Prefer the native worktree tool when it's available in your environment.** An `EnterWorktree`-style
+tool typically creates an isolated worktree (often under something like `.claude/worktrees/`, though
+the exact location is tool-dependent), switches the session into it, and tracks it for clean exit —
+which is exactly the lifecycle this skill wants, with no manual path management. The git path is the
+universal fallback and is exactly what the native tool does under the hood.
+
+| You have… | Create | Leave intact | Discard |
+| --- | --- | --- | --- |
+| A native worktree tool (`EnterWorktree`-style) | enter, named for the feature slug; the session's working directory moves into the isolated checkout | exit with `keep` — worktree and branch stay on disk for later | exit with `remove` — deletes both when the work is done or abandoned |
+| Plain git only | `git worktree add -b feat/<slug> .worktrees/<slug>` | leave the dir; it persists until its work lands | `git worktree remove` + `git branch -d` |
+
+Removing a worktree that holds uncommitted or unmerged work must be an explicit, confirmed choice,
+never a silent cleanup: refuse the silent path and confirm the discard with the user, quoting what
+would be lost.
+
+**You do not have to remember to clean up.** Once the work lands on the trunk, a `post-merge` hook
+retires the worktree and its branch on its own — it removes only what the reaper already classifies
+as safe, and anything holding unsaved work is refused exactly as it is above. Nothing to run, and
+nothing to remember: the previous version of this skill asked an agent to remember, and it was
+skipped on both features that reached that point.
+
+```bash
+# from the repo root, default branch up to date
+git fetch origin
+git worktree add -b feat/<slug> .worktrees/<slug> origin/<default-branch>
+# work happens in .worktrees/<slug>; the main checkout is untouched
+```
+
+**Inside the repo, always — never a sibling.** `.worktrees/` is already gitignored by the harness,
+the reaper already recognises it as its own, and the difference matters after the work lands: a
+sibling directory sits outside the tree, so it survives every cleanup of the repository and stops
+being visible to whoever would retire it. Two of them accumulated here before this was written down.
+Deleting the repo should delete its worktrees with it.
+
+```bash
+# branch-only path (the degenerate case: no separate directory needed)
+git switch -c feat/<slug> origin/<default-branch>
+```
+
+```bash
+# when the work has landed — the cleanup is the default, and it is a command, not a judgement call
+npx ai-hub worktrees reap
+```
+
+Either way, the contract is identical: **after this step, the cwd is an isolated branch off a clean
+base, and the default-branch checkout is exactly as it was.** Confirm that out loud, in
+one line, before handing to `implement`.
+
+### Cleanup is the default, and it is not yours to judge
+
+A worktree whose work is already in the trunk is retired **by default** — you do not decide that by
+reading the situation, because "is this safe to delete?" is a deterministic question and a wrong
+answer costs a directory that cannot be brought back. Ask the command:
+
+```bash
+npx ai-hub worktrees        # every landed worktree, with a verdict and a reason
+npx ai-hub worktrees reap   # retire the ones that are safe with nothing to lose
+npx ai-hub worktrees reap <path>   # retire one the user has just confirmed
+```
+
+Three things have to hold before a worktree is retired without asking, and each fails towards
+**keeping** it:
+
+- **ai-hub created it** — location *and* branch shape both match. Only one matches → it might be the
+  user's, so it is asked about, never removed silently. Neither → foreign; not touched, not offered.
+- **The branch adds nothing the trunk does not have** — asked about *content*, so a squash-merged
+  pull request counts as landed. Its branch is kept even so: git will not delete it safely, and while
+  it exists the commits survive a wrong call.
+- **Nothing inside would be lost** — not just "no pending changes": untracked and ignored files count,
+  because a worktree that git calls clean can still hold the only copy of a `.env` or a local
+  database. Installed dependencies and build output are the one carve-out.
+
+Anything else is reported with the reason and the way out. A refusal you cannot act on is not safety.
+
+**The native tool owns its own lifecycle.** If you isolated via a native `EnterWorktree`-style tool,
+exit through that tool's `remove`/`keep`; the reaper is for worktrees git alone knows about.
+
+**When the command is unavailable** (no ai-hub in this project), the manual equivalent is: confirm it is
+a linked worktree (`git rev-parse --git-dir` ≠ `--git-common-dir`), rule out a submodule
+(`git rev-parse --show-superproject-working-tree` must be empty), `cd` to the main working tree, then
+`git worktree remove` and `git worktree prune`. Never `-D` a branch to make the cleanup succeed.
+
+## Model tier — `light` (opt-in routing)
+
+This phase's default model tier is **`light`** — isolating the workspace is mechanical git work. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch in one line when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
+
+## Talking about it
+
+The isolation is identical for every reader; only the words change. In the `orient` voice: state
+the branch/dir in one line, add one line of *why* a worktree over a branch (or vice-versa) for this
+case, and confirm the base ref. For a `non-technical` reader, say what a worktree is with an
+everyday analogy (a second copy of the desk, so the first one stays as it was).
+
+A **dirty tree with the user's uncommitted work is always a hard stop for a confirmation** — no
+wish for brevity removes the check before risking someone's WIP.
+
+## Anti-patterns → STOP
+
+| Rationalization | Reality / Fix |
+| --- | --- |
+| "I'll just implement on `main`, it's a small change" | Small changes become commits on the wrong branch. Branch/worktree first — always, before the first edit. |
+| "There's uncommitted WIP, I'll stash it and switch" | A worktree avoids the stash entirely and can't drop it. Use a worktree; if you must stash, confirm with the user and name the stash. |
+| "I'll branch off local HEAD, fetching is slow" | Stale base = merge conflicts you pay for later. Branch off an up-to-date `origin/<default>` unless the user wants HEAD. |
+| "The worktree's dirty but I'll `remove --force` to clean up" | Force-removing a dirty/unmerged worktree throws away work irreversibly. Resolve or confirm explicitly first; never silent-force. |
+| "I'll name it `wip` / `temp` / `branch2`" | An untraceable name divorces the branch from its spec/plan, and the automatic cleanup will not claim it. Use `<type>/<slug>` — `feat/` for a feature, `fix/`, `docs/`, `chore/` for the rest. |
+| "I'll create the worktree AND start writing code right here" | This skill only isolates. Hand a clean isolated workspace to `implement`; don't blur the two steps. |
+| "Already on a feature branch, I'll make a worktree anyway" | Redundant isolation is just clutter. If the current branch is already isolated and clean, say so and proceed. |
+| "I'll record the worktree path into 02-DOCS so it's tracked" | Isolation is plumbing, not knowledge. No artifact; the branch name traces it. Don't pollute the wiki. |
+
+**Next:** with a clean isolated workspace in hand, hand to `../implement/SKILL.md` — walk the task
+list test-first, one commit per task, on this branch. Neighbours: `../tasks/SKILL.md` slices the plan
+before you get here; `../parallel/SKILL.md` decides *what may run concurrently* inside these
+workspaces — it leans on this skill (each independent stream gets its own worktree, so the streams
+never fight over files) but the partition-then-gather call is its own; `../ship/SKILL.md` closes the
+branch afterwards — merge, PR, or discard, with Daner Alejandro Salazar Colorado-only git authorship. This skill only *opens* the
+isolation, and it touches git state only: no runtime code, nothing under `02-DOCS`.

package/skills/shared/worktrees/evals/README.md

@@ -0,0 +1,78 @@
+# Eval harness — `worktrees` skill
+
+These evals are run by an **agent harness** (an LLM agent with the ai-hub Spec-Kit + stack skill catalog
+available), not a byte-exact shell script. `cases.yaml` is the fixture; this file is the procedure.
+Grading is judgment-based — a human or a judge-agent scores against the rubrics.
+
+`worktrees` is a process skill — an **on-demand** SDD step that runs right before `implement`. It is
+judged on **routing accuracy** (does it fire only when the intent is *isolate a workspace before
+code is touched*, and stay silent on the adjacent coding/cleanup/diagnosis steps) and **capability**
+(does it run the pre-flight gate, pick branch-vs-worktree correctly, prefer the native tool, and
+hand off without writing code).
+
+## 1. Triggering accuracy
+
+Goal: `worktrees` fires when the user wants an isolated workspace before implementing, and stays
+silent on the neighbouring steps (the coding loop, the task breakdown, the branch cleanup/ship, the
+debug protocol, the workspace bootstrap).
+
+1. Load **only** the `worktrees` skill description into the agent, plus the bare names of the sibling
+   skills for routing: the ai-hub Spec-Kit phases (constitution, specify, clarify, plan, tasks, analyze,
+   implement, verify, review, ship, debug, parallel) and the stack/other skills (fastapi, nextjs,
+   go, postgresdb, flutter, design, marketing, presentations, course-storytelling, building-agents,
+   secure-coding, deployment, harness, init). Do **not** load any skill bodies.
+2. For each prompt in `should_trigger` and `should_not_trigger`, ask the agent which skill (if any)
+   it would invoke. Run **3–5 trials per prompt** at production temperature to catch flakiness.
+3. Score:
+   - `should_trigger` → PASS if `worktrees` is selected in the majority of trials.
+   - `should_not_trigger` → PASS if `worktrees` is **not** selected; bonus-correct if it routes to
+     the `route_to` sibling named in the case.
+4. **Pass bar: ≥ 90% of prompts pass** (at most 1 miss across the 12 prompts), and no
+   `should_not_trigger` prompt may fire `worktrees` in a majority of its trials. The two
+   highest-value near-misses to get right are `implement` (the phase immediately after — coding on an
+   already-isolated branch must NOT re-trigger isolation) and `ship` (the phase that *closes* the
+   branch — merge/PR/cleanup is not this skill's open-isolation job).
+
+### Routing note (which siblings exist on disk)
+
+`route_to` is a conceptual label, not a link. All five near-miss targets — `implement`, `tasks`,
+`ship`, `debug`, `harness` — exist as skill directories in this repo, so each route is to a real
+sibling. The skill body links the resolvable cross-references it uses (`../implement/SKILL.md`,
+`../tasks/SKILL.md`, `../ship/SKILL.md`) and names the on-demand `parallel` / `debug` patterns in
+prose; verify links still resolve if the catalog is reorganized.
+
+## 2. Capability uplift (with vs without)
+
+Goal: the skill measurably improves the isolation step, not just gates it.
+
+1. For the `capability` scenario, run the agent **twice**:
+   - **WITHOUT**: base agent, no `worktrees` skill loaded.
+   - **WITH**: same prompt, `worktrees` skill fully loaded.
+2. Grade each output against the `must_include` checklist — count a point only if it is genuinely
+   satisfied, not merely gestured at. The load-bearing points are: the pre-flight gate (repo +
+   branch + `git status` before acting), the branch-vs-worktree decision justified by the live dev
+   server, preferring the native tool with a git fallback, a slug-matched name, and handing off to
+   `implement` without writing code.
+3. Coverage = points satisfied / total points, per run.
+4. **Pass bar:**
+   - WITH-skill coverage **≥ 80%** of the rubric.
+   - WITH clearly beats WITHOUT. The signature uplift to look for: the WITHOUT run tends to run a
+     bare `git checkout -b` (or even start editing on `main`), skip the dirty-tree check, ignore the
+     native tool, and blur straight into writing code; the WITH run runs the pre-flight gate, picks a
+     *worktree* because a process is live on the current files, names it `feat/<slug>`, confirms the
+     main checkout is untouched, and hands to `implement`.
+5. Run 2–3 trials per condition and average; note any rubric point the skill never produces — that is
+   a gap to fix in `SKILL.md`.
+
+## Notes
+
+- Prompts deliberately vary phrasing; several omit the word "worktree" (the live-dev-server case, the
+  dirty-WIP case) so triggering rests on the signal "isolate a workspace before touching code", not
+  keyword matching.
+- Near-misses route to the genuinely correct sibling: already-isolated-now-code → implement,
+  plan-to-checklist → tasks, merge/PR/cleanup → ship, failing-test-root-cause → debug,
+  workspace-bootstrap → harness.
+- The one unrecoverable failure mode for this skill is bulldozing a user's uncommitted WIP; the
+  capability rubric and the SKILL.md red flags both gate on checking `git status` before acting.
+- This is judgment-based, not byte-exact. Record trial counts and the judge (human or model)
+  alongside results for reproducibility.

package/skills/shared/worktrees/evals/cases.yaml

@@ -0,0 +1,47 @@
+skill: worktrees
+
+should_trigger:
+  - prompt: "Before we start building this feature I want it isolated from my main checkout — set up a worktree so my open files don't get disturbed."
+    why: "Explicit request for filesystem isolation via a worktree before code is touched — the exact job this skill owns."
+  - prompt: "I'm on main and about to implement the plan. I don't want to dirty my working tree — get me onto something I can throw away."
+    why: "On the default branch, implement is next, wants disposable isolation first — the on-demand gate that runs right before implement."
+  - prompt: "Spin up an isolated checkout on a branch for the checkout-reservation work, branched off an up-to-date main."
+    why: "Isolated checkout + feature branch + fresh base ref is precisely the worktree creation flow, including the base-ref decision."
+  - prompt: "My dev server is running against the current files and I need to start a second stream of work without yanking the files out from under it."
+    why: "Live process on current files is the textbook reason to prefer a worktree over a branch switch — non-obvious phrasing, no keyword 'worktree'."
+  - prompt: "I've got uncommitted WIP I want to keep, but I also need to start the new feature cleanly somewhere else. How do I do both?"
+    why: "Dirty tree + need both the WIP and clean new work is the canonical worktree case (avoid the stash, isolate the new work)."
+  - prompt: "Keep the working tree clean while I execute this plan — create the branch/worktree and then we code."
+    why: "Wants isolation established before executing the plan, then hand to implement — the open-isolation-then-handoff contract."
+  - prompt: "Make me a parallel checkout for feat/notifications so I can build it alongside what I already have open."
+    why: "Parallel checkout for a named feature branch alongside existing open work — a worktree by definition, even without the framing of SDD phases."
+
+should_not_trigger:
+  - prompt: "The isolated branch is ready. Now walk the task list test-first and write the code, one commit per task."
+    route_to: "implement"
+    why: "Isolation already exists; this is the test-first coding loop, which is implement, not the workspace-setup step."
+  - prompt: "We have the approved plan. Break it into an ordered checklist where each item has a done-check I can verify."
+    route_to: "tasks"
+    why: "Slicing the plan into an ordered, verifiable task list is the tasks phase; no isolation request here."
+  - prompt: "The feature's built and all tests pass. Merge the branch, open the PR, and clean up the worktree afterward."
+    route_to: "ship"
+    why: "Closing the branch — merge/PR/cleanup with human-only authorship — is the ship phase; this skill only OPENS isolation."
+  - prompt: "A test is failing for a reason I don't understand on this branch. Help me find the root cause before I change anything."
+    route_to: "debug"
+    why: "Root-cause diagnosis of a failing test is the debug protocol, not workspace isolation."
+  - prompt: "I want the canonical docs/tools and docs/ layout set up for this workspace and the root AGENTS.md generated."
+    route_to: "harness"
+    why: "Bootstrapping the workspace control plane is the harness skill; nothing to do with git isolation for a feature."
+
+capability:
+  - scenario: "User says: 'I'm on main with a clean tree, the plan for the order-reservation feature (slug: order-reservation) is approved, and I'm about to implement it. My editor and a dev server are open against the current files. Set up isolation.' The agent has the worktrees skill loaded and a native worktree tool available."
+    must_include:
+      - "Runs the pre-flight gate: confirms it's a git repo, checks current branch (main), and checks `git status --short` for tree state before creating anything"
+      - "Reads the register from AGENTS.md and narrates briefly in that register (branch/dir in one line plus one line of why)"
+      - "Chooses a WORKTREE over a plain branch and justifies it by the live dev server / open editor on the current files (a branch switch would yank files from the running process)"
+      - "Prefers the native worktree tool (EnterWorktree-style) for creation and session-switch, naming it for the slug (feat/order-reservation); states the git `git worktree add -b feat/order-reservation … origin/<default>` fallback if no native tool exists"
+      - "Branches from an up-to-date default base (fresh origin/<default>) rather than stale local HEAD, or asks which the user wants"
+      - "Names the workspace to match the spec/plan slug (feat/order-reservation) so branch, spec, and plan are traceable"
+      - "Confirms the contract out loud: cwd is now the isolated branch and the main checkout is untouched"
+      - "Writes NO runtime code and NO docs/ artifact in this step (isolation is plumbing, not knowledge)"
+      - "Hands off to the implement phase rather than starting to write the feature code itself"