@jeiemgi/cckit 0.1.6

package/skills/kit-annotate/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: kit-annotate
+description: Set up and run in-app visual UI annotation for a React project, wired to Claude via Agentation. Use AUTOMATICALLY when the user asks to set up / install visual annotation or an annotation toolbar, "annotate the UI / a component", click-to-annotate, give the agent visual UI feedback, review or triage UI annotations, or run "watch mode" for UI feedback. Targets a React app (Next.js, Vite, or React Router); installs the third-party `agentation` dev dependency + its MCP. Other agents are out of scope — this wires Claude Code only.
+argument-hint: "[setup | watch | review | status] [--dry-run]"
+allowed-tools: Bash, Read, Edit, Glob, Grep, AskUserQuestion, mcp__agentation__agentation_get_all_pending, mcp__agentation__agentation_watch_annotations, mcp__agentation__agentation_acknowledge, mcp__agentation__agentation_resolve, mcp__agentation__agentation_dismiss, mcp__agentation__agentation_reply, mcp__agentation__agentation_list_sessions, mcp__agentation__agentation_get_session, mcp__agentation__agentation_get_pending
+---
+
+# kit-annotate — visual UI annotation for React, wired to Claude
+
+This sets up and drives **click-to-annotate** UI feedback for a React app. You point at a component in
+your running dev app and leave a note; Claude reads a structured record and fixes the code. It **adopts
+Agentation** — a maintained, source-available (PolyForm Shield 1.0.0) npm package — as the capture
+engine, and wires it into Claude: install, MCP registration, a project rule, and the fix loop. The kit
+vendors none of Agentation's code; it installs it as the project's own dev dependency.
+
+**Scope is Claude Code only.** Agentation is agent-agnostic on its own (Cursor/Codex via its MCP/export),
+but the kit wires and maintains the Claude path only — say so if asked about other agents.
+
+The kit lives at `${CLAUDE_PLUGIN_ROOT}`; the setup engine is
+`${CLAUDE_PLUGIN_ROOT}/scripts/annotate-setup.sh` (which sources `scripts/lib/react-detect.sh`).
+
+## 0. Orient
+
+- Read `./.claude/kit.config.json` if present. If `.annotate.enabled == true`, this project is already
+  set up → default to **watch/review**. Otherwise default to **setup**. Honor an explicit
+  `$ARGUMENTS` mode (`setup` · `watch` · `review` · `status`) over the inference.
+- No `.claude/` at all? Setup still works, but mention that running `/kit-init` first gives the full
+  integration (the rule lands in `.claude/rules/`, and memory enables the on-close summary).
+
+## 1. Setup mode
+
+1. **Detect + preview.** Run the engine in dry-run from the project root and show the plan:
+   ```bash
+   "${CLAUDE_PLUGIN_ROOT}/scripts/annotate-setup.sh" --dry-run
+   ```
+   If it reports **No React app detected**, stop — this targets React apps. If the framework is
+   `react` (unrecognized: CRA/Gatsby/etc.), tell the user you'll install + register but they must wire
+   the `<Agentation />` line manually.
+2. **Explain what becomes doable, then ask consent.** In plain terms: *click a component in your dev
+   app → leave a note → Claude reads the component + selector + source path + your comment and fixes
+   it; optionally hands-free, where Claude watches for new notes and resolves them as you go.* State the
+   **honest limits** up front — dev-only (stripped from production); identity is selector + source-path
+   + component name, **not** live prop/state values, so Claude greps to the file; React Server
+   Components degrade to a selector. Note the **license**: Agentation is PolyForm Shield, free for this
+   use, installed as the user's own dev dependency. Then `AskUserQuestion`:
+   **Install** · **Preview only (dry-run)** · **Skip**.
+3. **Install.** On consent, run the engine for real (no `--dry-run`). It installs the dep, registers the
+   `agentation` MCP for Claude, writes `.claude/rules/react-annotate.md`, and records `.annotate` in
+   `kit.config.json`.
+4. **Wire the dev-only toolbar into the app entry — via `Edit`, showing the change first.** The engine
+   prints the exact snippet + the detected entry file. **The `endpoint` prop is mandatory** — without it
+   the toolbar boots `disconnected`, writes only to `localStorage`, and annotations never reach the MCP
+   receiver (Claude sees 0 sessions). Use the port from `kit.config.json → annotate.mcp.httpPort`
+   (default `4747`). Apply it per framework:
+
+   | Framework | Entry file | How to wire |
+   | --------- | ---------- | ----------- |
+   | **Next.js (App Router)** | `app/layout.tsx` | Add `import { Agentation } from "agentation"` and, inside `<body>` after `{children}`, `{process.env.NODE_ENV === "development" && <Agentation endpoint="http://localhost:4747" />}`. The component is a client component; if `layout.tsx` is a Server Component, render it from a tiny `'use client'` wrapper, or place it in a client root. |
+   | **Next.js (Pages Router)** | `pages/_app.tsx` | Same import; render `{process.env.NODE_ENV === "development" && <Agentation endpoint="http://localhost:4747" />}` after `<Component {...pageProps} />`. |
+   | **Vite** | `src/main.tsx` | Import it; render `{import.meta.env.DEV && <Agentation endpoint="http://localhost:4747" />}` next to `<App />` inside the root render. |
+   | **React Router v7 (framework mode)** | `app/root.tsx` | Import it; render the `import.meta.env.DEV`-gated `<Agentation endpoint="http://localhost:4747" />` inside the `<body>` of the root layout. |
+
+   Confirm the exact insertion point with the user, show the diff, then save. Never blind-edit.
+5. **Finish.** Tell the user to: **restart Claude Code** (so it loads the `agentation` MCP), start the
+   **dev server**, and verify with `npx agentation-mcp doctor`. Then they can annotate.
+
+## 2. Watch / review mode (a live session)
+
+1. **Preflight.** Confirm the `agentation_*` MCP tools are available (if not → restart Claude Code;
+   `npx agentation-mcp doctor`). Confirm the dev server is up and the toolbar shows bottom-right.
+   Then call `agentation_list_sessions`: **connected but 0 sessions ⇒ the `endpoint` prop is missing
+   from the wired `<Agentation />` or the browser tab is stale** — fix the wiring / reload before
+   handing off, rather than waiting on a watch that will never see anything.
+2. **Default to the batch contract.** Open with: *"Annotate everything you want changed, then come back
+   and say 'done' — I'll pull the whole batch and apply the fixes."* When they say done, call
+   `agentation_get_all_pending`. This lets the user mark up the whole screen and hand off a reviewed
+   batch, instead of being interrupted mid-thought.
+   - **Hands-free is opt-in.** Only call `agentation_watch_annotations` (which blocks silently for
+     minutes and picks notes up one at a time) if the user explicitly asks to "watch" / go hands-free.
+3. **Set expectations explicitly** (so the browser side isn't a silent black box): notes flip
+   **acknowledged → resolved** in the toolbar as you work; fixes land via **HMR** — *refresh to see
+   them*; each resolved note carries a **one-line summary** of the change.
+4. **Run the loop** (also encoded in `.claude/rules/react-annotate.md`): for each annotation →
+   `agentation_acknowledge` → locate the code (source path if present, else grep selector / component /
+   nearby text) → make the fix per project conventions → `agentation_resolve` with a one-line summary
+   (or `agentation_dismiss` with a reason / `agentation_reply` to ask). In hands-free, loop on
+   `agentation_watch_annotations` until the user stops.
+5. **On close.** If the project has memory enabled, write a short MemPalace summary to the project wing
+   (resolved annotations, files touched, deferred items) before the closing summary.
+
+## 3. Status mode
+
+- Print `.annotate` from `kit.config.json`; run `npx agentation-mcp doctor`; if the MCP is live, call
+  `agentation_list_sessions` to show active annotation sessions.
+
+## Rules
+
+- **Consent-gated + reversible.** Ask before installing, before editing the app entry (show the diff),
+  and before registering the MCP. Setup is idempotent — re-running is safe.
+- **Don't vendor Agentation.** Only ever `install` it into the user's project; never copy its source
+  into the kit (PolyForm Shield noncompete).
+- **Be honest about limits** every time: dev-only, no prop/state values (grep to the file), RSC degrades
+  to a selector. Don't claim file:line is guaranteed.
+- **Claude-only scope.** If asked about Cursor/Codex, point to Agentation's own MCP/`npx add-mcp`; the
+  kit doesn't wire them.
+- Don't reimplement Agentation's Next-only `/agentation` skill — this skill's job is the broader
+  framework coverage (Vite + React Router) plus the Claude-kit loop, rule, and MCP wiring.

package/skills/kit-autopilot/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: kit-autopilot
+description: Autonomous execution under hard caps — run ONE long objective hands-off, OR drive the planned effort/flow set in parallel. On an APPROVED plan the captain DECIDES, MERGES each wave, and CONTINUES; it pings the human ONLY on a genuine blocker. THIN wrapper over the built-in /loop + the kit's orchestrate scripts; never a new engine.
+when_to_use: When delegating work to run unattended — a single capped objective (overnight) or several planned flows at once without tab-juggling. A verifiable stop condition is required. Maps to Kun Chen's "Good Night Have Fun" (the loop) and "First Mate" (the multi-flow captain). Not for one-off tasks (just do them) or open-ended work with no measurable stop.
+---
+
+# kit-autopilot — capped, hands-off execution
+
+One skill, two modes — both delegate work that runs **autonomously to a verifiable stop, under hard
+caps**. It is a **thin wrapper**: it composes the built-in `/loop` and the kit's `orchestrate`
+scripts; it never reimplements looping or orchestration.
+
+| Mode          | What runs                                                   | Wraps                                                         |
+| ------------- | ----------------------------------------------------------- | ------------------------------------------------------------- |
+| **objective** | one long objective on the current branch                    | the built-in `/loop` + caps + a stop-check                    |
+| **plan**      | the planned, file-disjoint set of efforts/flows in parallel | `kit effort plan` + `orchestrate.sh` + `orchestrate-watch.sh` |
+
+## Established-plan autonomy (the default)
+
+**When the plan is already approved, the captain DECIDES + MERGES + CONTINUES — it does not bounce
+back to the human to confirm a planned step.** "Do these efforts with the new flow", an approved
+`kit effort plan`, or a green wave are an **established plan**: execute it end to end —
+build a wave → merge its PRs → close subs+parent → gc → launch the next wave — **without asking
+"merge or review?"**. A planned merge is _execution_, not a new decision. (José, "Error 1", 2026-06-28.)
+
+- The human steers the **plan**, not each merge. Asking to confirm a routine planned merge is the error.
+- A `risk:med` change the plan already approved (a product feature in the agreed scope) is **not** a
+  reason to stop — the plan blessed it. The risk-tiered review tiers
+  (`risk-tiered-review.md`) govern **ad-hoc** PRs, **not** execution of an approved plan.
+
+### Ping the human ONLY on a genuine blocker
+
+Interrupt only when the plan genuinely can't proceed without a human:
+
+- an **unresolvable merge conflict** the captain can't safely resolve;
+- a **surprise always-human change not implied by the plan** — a NEW dependency/lockfile,
+  security/auth/secret, or `.github/workflows/**` edit the plan didn't call for;
+- a **real ambiguity the plan doesn't cover** (a fork the approved scope is silent on);
+- a **destructive/irreversible step outside the plan**.
+
+Everything else: decide, land it, report on completion. Quiet by default, loud only on a true blocker.
+
+## The contract (hard — both modes)
+
+- **Caps are mandatory and hard.** A run declares a token budget, an iteration cap, and a
+  **verifiable** `--until` stop-check. Autopilot refuses to start without them and never raises its
+  own budget mid-run.
+- **Plan mode merges its waves.** Driving an approved plan, the captain merges each wave's PRs
+  (squash), closes subs+parent, and gc's — then advances any effort that was `blocked_by` it.
+- **Objective mode never auto-merges its own run.** A single capped objective lands commits on its
+  branch; the merge is the captain's/human's call under the plan, not the loop's.
+- **Never free-spawn (plan mode).** The parallel set comes from `kit effort plan`, never improvised;
+  co-launch only **file-disjoint** efforts (sequence the rest).
+
+## Mode: objective (single capped run)
+
+```
+kit autopilot "<objective>" --max-tokens N --max-iters K --until "<check>"
+```
+
+| Flag                | Meaning                                                                     | Default  |
+| ------------------- | --------------------------------------------------------------------------- | -------- |
+| `<objective>`       | the goal in one line (e.g. "make the build pass and open a PR")             | required |
+| `--max-tokens N`    | hard token budget for the whole run                                         | required |
+| `--max-iters K`     | hard cap on loop rounds                                                     | required |
+| `--until "<check>"` | a command that exits 0 when done (`typecheck`, a build, a test, a PR state) | required |
+
+**Execution:** validate caps -> drive `/loop` with the objective -> after each round evaluate the
+stop conditions -> commit each round's progress (commit-early; an unattended run must be durable if
+the session dies). Work stays on the branch it started on (one branch per worktree).
+
+## Mode: plan (drive the parallel set)
+
+```
+kit autopilot --plan            # read the plan and launch the planned set
+```
+
+1. **Read the plan** — `kit effort plan` groups open efforts by `flow:`, orders each flow by its
+   `blocked_by` edges, sizes each by `ctx:*`, and declares fan-out per effort via `par:*`. That
+   output IS the launch plan — the set, the order, and the budget are read from it, not chosen.
+2. **Launch** — `orchestrate.sh <issueA> <issueB> ...` (one worktree per effort, file-disjoint;
+   respect `par:*`/`blocked_by` so blocked efforts wait). Use `--notify`.
+3. **Babysit** — `orchestrate-watch.sh` (launched by `--notify`) signals PR open / conflict / failing
+   checks / merged, and GCs each worktree + branch on merge.
+4. **Decide + advance** — as each wave's gates go green, **merge it** (established-plan autonomy
+   above) and advance any effort that was `blocked_by` it. Surface to the human only a genuine blocker.
+
+## On wake / on a pause (the report — always)
+
+- **Branch(es)** + final short HEAD, or per-flow PRs (plan mode).
+- **Commits made** this run (count + one-line subjects).
+- **Why it stopped** — cap hit / check passed / stalled / waves landed / a genuine blocker (what + the decision needed).
+- **State** — objective verifiably done, or parked (and the next step a human needs).
+
+## Stop conditions (any one ends a run)
+
+1. **Cap hit** — `--max-tokens` or `--max-iters` reached.
+2. **Check passes** — `--until` exits 0, or all planned waves are merged.
+3. **No new progress** — no new commit / no measurable advance for K rounds (stall guard).
+4. **Genuine blocker** — pause + report (see above).
+
+## Rules
+
+- **Never start without a verifiable check** — an uncapped, uncheckable run is banned.
+- **Thin wrapper only** — never grow a second loop or orchestration engine here; if `/loop` or the
+  orchestrate scripts lack something, fix them at the source.
+- **Adopt-first** — evaluate Kun Chen's open-source **GNHF** (the loop) and **First Mate** (the
+  captain) before extending this native skill; this is the thin native version.

package/skills/kit-contribute/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: kit-contribute
+description: Contribute your additions and requests back upstream to claude-kit as a GitHub PR (or issue). Use AUTOMATICALLY whenever the user asks to contribute to claude-kit, submit a PR, open a PR upstream, propose a change to the kit, give back to the kit, share my agent / skill / profile with the kit, send or file a feature request, or request a feature. Opens a pull request (or, for a pure idea, an issue) against the kit's upstream repo. Works from a project scaffolded by /kit-init and customized with /kit-customize, but also stands alone.
+argument-hint: "[agent <name> | skill <name> | profile <name> | request]"
+allowed-tools: Bash, Read, Edit, Write, Glob, Grep, AskUserQuestion, Skill
+---
+
+# kit-contribute — give your additions back to claude-kit
+
+You help a **downstream user submit a contribution upstream** to the claude-kit repo as a GitHub
+**PR** — a new agent, skill, or profile — or, for a pure idea, a GitHub **issue**. The kit (templates
++ profiles) lives at `${CLAUDE_PLUGIN_ROOT}`; the user's project lives in `./.claude/`. You never push
+to the installed plugin dir — you work in a fresh temp clone of the upstream repo.
+
+This is the **inverse of `/kit-customize`**: where customize *parameterizes a template into a project*,
+you *de-parameterize a project artifact back into a reusable kit template*.
+
+## 1. Resolve upstream
+
+- The kit ships **inside `jeiemgi/cckit`** at `` — there is no
+  standalone `claude-kit` repo. Read `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json` → `repository`
+  for `OWNER/REPO` (default `jeiemgi/cckit`); contributing = a PR to that repo touching
+  `**`. **Confirm `OWNER/REPO` with the user.**
+- Require GitHub auth: run `gh auth status`. If not logged in, **stop** and tell the user to run
+  `gh auth login` first — every step below needs it.
+
+## 2. Pick a contribution type
+
+If `$ARGUMENTS` names one (`agent`, `skill`, `profile`, `request`), use it. Otherwise ask via
+`AskUserQuestion`:
+
+| Type                    | What it adds                                  | Target path                              |
+| ----------------------- | --------------------------------------------- | ---------------------------------------- |
+| **Agent**               | a reusable agent template                     | `templates/agents/<name>.md`             |
+| **Skill**               | a `SKILL.md` (scaffolded or plugin)           | `templates/skills/<name>/` or `skills/<name>/` |
+| **Profile**             | a preset role profile JSON                    | `profiles/<name>.json`                   |
+| **Feature request / idea** | a proposal — GitHub **issue** by default   | (issue) or `requests/<slug>.md`          |
+
+## 3. Assemble the artifact
+
+### Agent — de-parameterize back into a template
+
+Take a project agent `./.claude/agents/<name>/AGENT.md` and **invert kit-customize's substitution**:
+
+| Concrete value in the project agent      | Replace with        |
+| ----------------------------------------- | ------------------- |
+| the project's name                        | `{{PROJECT_NAME}}`  |
+| the working language                      | `{{COMMS_LANG}}`    |
+| the project's MemPalace wing              | `{{WING}}`          |
+| the project's slug                        | `{{PROJECT_SLUG}}`  |
+
+- **Re-wrap the `## Memory (MemPalace)` section** in `<!-- IF:MEMORY -->…<!-- /IF:MEMORY -->`. If the
+  project had memory **off** (no Memory section), **add** the block with the standard MemPalace table
+  (wing=`agent-<name>` for diary, `{{WING}}` for shared rooms — match `templates/agents/n8n.md`).
+- **Strip anything project-specific or secret** — concrete repo names, hostnames, IDs, tokens,
+  credential names. Read `kit.config.json` to know exactly which literals to swap out.
+- Keep the frontmatter contract intact (`name` = file basename, `description`, `when_to_use`,
+  `tools`, `skills`). Target: `templates/agents/<name>.md`.
+
+### Skill — a SKILL.md
+
+Ask whether it's a **scaffolded skill** (lands in a project's `.claude/skills/` via init) →
+`templates/skills/<name>/SKILL.md`, or a **plugin skill** (ships with the plugin itself) →
+`skills/<name>/SKILL.md`. Strip project-specific paths/values.
+
+### Profile — a preset JSON
+
+Often the user already saved one via kit-customize at `~/.claude/kit-profiles/<name>.json`. Match the
+preset shape exactly (`name`, `label`, `description`, `agents`, `skills`, `rules`, `roles`,
+`milestones`, `defaults`) — see `profiles/automation.json`. **Verify every agent it lists exists** as
+`templates/agents/<agent>.md` in the upstream clone (step 4) — bundle any missing agent template in
+the **same PR**, or drop it from the list. Target: `profiles/<name>.json`.
+
+### Feature request / idea — a proposal
+
+Author a concise proposal with these sections: **Problem · Proposal · Scope · Why**. By default this
+goes as a GitHub **issue** (lowest friction — no clone needed). Offer the alternative of a PR that adds
+`requests/<slug>.md` with the same content if the user prefers a tracked file.
+
+### Lint before submitting (agent / skill / profile only)
+
+Validate before you ever push. Reuse existing tooling via the `Skill` tool:
+
+- **Agents** → run `claude-kit:kit-customize`'s lint (frontmatter, required keys, name↔file, tools
+  shape, skills resolve, **no leftover `{{VAR}}`** except the intended template tokens).
+- **Skills** → defer to `agent-skills:skill-crafting`.
+- **Profiles** → validate JSON parses + agent references resolve (above).
+
+**Block on hard failures.** Fix or stop; don't submit a broken artifact.
+
+## 4. Determine access & prepare a clone
+
+Check permission: `gh repo view OWNER/REPO --json viewerPermission -q .viewerPermission`.
+
+| Permission                  | Path                                                                       |
+| --------------------------- | -------------------------------------------------------------------------- |
+| WRITE / MAINTAIN / ADMIN    | clone upstream: `gh repo clone OWNER/REPO <tmp>`; branch `contrib/<type>-<name>` |
+| READ / none                 | **fork**: `gh repo fork OWNER/REPO --clone --fork-name claude-kit` into a `<tmp>`; branch off `main` |
+
+- Use a fresh temp dir (e.g. `mktemp -d`). **Never** push from `${CLAUDE_PLUGIN_ROOT}` or the
+  marketplace cache — they're managed/detached.
+- Never assume push rights to upstream — fork whenever you lack write access.
+- Place the assembled artifact (step 3) at its correct path **inside the temp clone**.
+
+## 5. Commit & push
+
+- `git add` the file(s) at the correct kit path.
+- Commit with a clear, scoped message: `feat(agent): add <name>`, `feat(skill): add <name>`,
+  `feat(profile): add <name>`.
+- Push the branch to the fork/origin (`git push -u origin <branch>`).
+
+## 6. Open the PR — confirm first (outward-facing)
+
+**This is public + outward-facing — confirm with the user before opening it.**
+
+- Artifact PR: `gh pr create --repo OWNER/REPO --base main` — from a fork the head is
+  `<your-login>:<branch>`. Title summarizes the contribution; body states **what it adds, why, and how
+  it was tested/linted**.
+- Pure request, no artifact: `gh issue create --repo OWNER/REPO` with the **Problem · Proposal · Scope
+  · Why** body instead.
+- Print the resulting URL.
+
+## 7. Report
+
+Print the PR/issue URL. Remind the user that a **maintainer reviews before it merges**, and that once
+merged they'll receive it via `claude plugin update`.
+
+## Rules
+
+- Always go through a PR or issue — **never push to upstream `main`**.
+- Fork when you lack write access; work in a temp clone, **never** the installed plugin dir.
+- Lint contributed agents/skills and de-parameterize agents (strip every project-specific + secret
+  value) before submitting.
+- **Confirm with the user before opening** the PR/issue — it's public and outward-facing.

package/skills/kit-customize/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: kit-customize
+description: Customize a kit-scaffolded project's .claude/ setup. Use AUTOMATICALLY whenever the user asks to create, add, edit, modify, rename, delete, or remove an agent in a project — and also to add a skill to an agent, attach skills, wire tools, find or search for a skill, suggest agents/skills for my project, lint my agents, validate an agent, build a custom profile, or pick a preset profile. Works on a project already scaffolded by /kit-init (a `.claude/` dir with `.claude/kit.config.json`).
+argument-hint: "[add-agent <name> | add-skill <agent> | lint | profile]"
+allowed-tools: Bash, Read, Edit, Write, Glob, Grep, AskUserQuestion, Skill
+---
+
+# kit-customize — tailor a kit-scaffolded project
+
+You customize an **already-scaffolded** claude-kit project: add agents, wire skills + tools onto
+them, search/suggest skills, lint everything, and apply a preset or custom profile. The kit (presets
++ templates) lives at `${CLAUDE_PLUGIN_ROOT}`; the project's setup lives in `./.claude/`.
+
+## 1. Load context
+
+- Read `./.claude/kit.config.json` → current `profile`, `roles`, `project.{name,slug,language}`,
+  `memory.enabled`. **If it's missing, stop**: tell the user to run `/kit-init` first — this skill
+  only customizes a project the kit already scaffolded.
+- List existing agents: `.claude/agents/*/AGENT.md` (Glob). Note their `name`s.
+- Available raw material:
+  - Preset profiles → `${CLAUDE_PLUGIN_ROOT}/profiles/*.json`
+  - Agent templates → `${CLAUDE_PLUGIN_ROOT}/templates/agents/<name>.md`
+  - Skill templates → `${CLAUDE_PLUGIN_ROOT}/templates/skills/<name>/SKILL.md`
+
+## 2. Pick a mode
+
+If `$ARGUMENTS` names one (`add-agent`, `edit-agent`, `delete-agent`, `add-skill`, `lint`, `profile`),
+use it. If the user's request clearly says create/add, edit/modify/rename, or delete/remove an agent,
+go straight to that path in step 3 — don't ask the mode. Otherwise ask via `AskUserQuestion`:
+**Add an agent** · **Edit an agent** · **Delete an agent** · **Add skills/tools** ·
+**Search/suggest skills** · **Lint** · **Profile (preset or custom)**.
+
+## 3. Add, edit, or delete an agent
+
+**Add** — two paths, ask which:
+
+- **From a kit template** — copy `${CLAUDE_PLUGIN_ROOT}/templates/agents/<name>.md`, then:
+  - substitute `{{PROJECT_NAME}}`, `{{COMMS_LANG}}`, `{{WING}}`, `{{PROJECT_SLUG}}` etc. from
+    `kit.config.json`;
+  - resolve the `<!-- IF:MEMORY -->…<!-- /IF:MEMORY -->` block — **keep** its inner content when
+    `memory.enabled` is true, **delete** the whole block (markers + body) when false.
+- **Fresh custom agent** — author one that follows the frontmatter contract (see below).
+
+Frontmatter contract (match the templates exactly):
+```yaml
+---
+name: <slug>            # must equal the agent's directory name
+description: <one line — what it owns + when it's invoked>
+when_to_use: <trigger conditions>
+tools: [Bash, Read, Edit, Write, Grep, Glob, mcp__server__tool, ...]
+skills:
+  - bare-global-skill
+  - plugin:skill
+---
+```
+Body: terse `## Authority` (✅ owns / ❌ defers + ❌ never), a numbered workflow, `## Voice + style`,
+and (only if memory enabled) the `## Memory (MemPalace)` table.
+
+Write to `.claude/agents/<name>/AGENT.md`. Then **lint it (step 6)**. Offer to:
+- add the agent's role to `kit.config.json` `roles`, and
+- add a row to the agent table in the project's `CLAUDE.md`.
+
+**Edit** — open `.claude/agents/<name>/AGENT.md` and change frontmatter (`description`, `when_to_use`,
+`tools`, `skills`) or body; for skills/tools specifically use step 4. To **rename**, move the dir to
+`.claude/agents/<new>/AGENT.md`, set `name: <new>`, and update its role in `kit.config.json` + the
+`CLAUDE.md` table. Keep edits additive; **re-lint (step 6)** after.
+
+**Delete** — **confirm explicitly first** and show what will be removed. Then delete the whole
+`.claude/agents/<name>/` directory and clean up references: drop the role from `kit.config.json`
+`roles`, remove its row from the `CLAUDE.md` agent table, and grep `.claude/` for other mentions —
+warn if any agent or rule still references it. Never delete without confirmation.
+
+## 4. Add skills/tools to an agent
+
+Open `.claude/agents/<name>/AGENT.md` and edit additively:
+
+- **`skills:`** — append bare global names, `plugin:skill` refs, or scaffolded project skills.
+- **`tools:`** — append builtins (`Bash`, `Read`, `Edit`, `Write`, `Grep`, `Glob`, `AskUserQuestion`)
+  and domain `mcp__<server>__<tool>` names.
+
+**Verify every name resolves before adding** (see step 5) — never invent a skill or tool name.
+Re-lint (step 6) after editing.
+
+## 5. Search / suggest skills (and tools)
+
+- **Discover** — invoke the `find-skills` skill via the `Skill` tool, and enumerate what's already
+  available: the session's skill list, `~/.claude/skills/*`, and installed plugin skills. For tools,
+  scan the available `mcp__*` names in this session.
+- **Suggest by profile/roles** — map the project to relevant skills + tools. Read what's actually
+  available rather than hardcoding; the table below is illustrative:
+
+  | Profile / role     | Skills (examples)                                                       | Tools (examples)        |
+  | ------------------ | ----------------------------------------------------------------------- | ----------------------- |
+  | software           | `agent-skills:context7`, `claude-api`, `playwright-best-practices`      | `mcp__chrome-devtools__*` |
+  | design / content   | `tailwind-design-system`, `gsap-*`, `gws-slides`                        | `mcp__paper__*`         |
+  | automation         | `n8n-*` (mcp-tools-expert, workflow-patterns, …)                       | `mcp__n8n__*`           |
+  | research           | `deep-research`                                                         | `WebSearch`, `WebFetch` |
+
+- Present the candidates and let the user pick which to wire into which agent → hand off to step 4.
+
+## 6. Lint (must pass)
+
+Validate one agent (`add-agent`/`add-skill` follow-up) or all (`lint` mode). Per file check:
+
+| Check                | Pass condition                                                        |
+| -------------------- | --------------------------------------------------------------------- |
+| Frontmatter          | opens & closes with `---`; parses as valid YAML                       |
+| Required keys        | `name`, `description`, `when_to_use`, `tools`, `skills` all present    |
+| Name = dir           | `name` equals the parent directory name                               |
+| Tools shape          | a list; each is a known builtin or matches `mcp__<server>__<tool>`     |
+| Skills resolve       | a list; each resolves as global / `plugin:skill` / project skill — **warn** if not |
+| No template tokens    | no leftover `{{VAR}}` in a scaffolded agent                           |
+
+Report a table: **file · check · pass/warn/fail**, then offer to fix the fixable ones (missing keys,
+name↔dir mismatch, unsubstituted tokens). For deeper skill authoring/validation, defer to
+`agent-skills:skill-crafting` via the `Skill` tool.
+
+## 7. Profile — preset or custom
+
+- **Preset** — read `${CLAUDE_PLUGIN_ROOT}/profiles/*.json`, show each `label` + `description` +
+  `agents`; on pick, scaffold/adapt its agents (step 3) and offer its `skills` to relevant agents.
+- **Custom** — choose any subset/superset of agents (templates or fresh) + skills + `roles` +
+  `milestones`. Offer to **save it for reuse** to `~/.claude/kit-profiles/<name>.json` using the
+  preset JSON shape (`name`, `label`, `description`, `agents`, `skills`, `rules`, `roles`,
+  `milestones`, `defaults`) — note it can feed a future `/kit-init` or kit-customize run.
+
+Either way, update `.claude/kit.config.json` `profile` + `roles` to reflect the active selection.
+
+## Rules
+
+- Never overwrite an existing agent file without confirming.
+- Always lint after writing or editing an agent (step 6).
+- Don't invent skill or tool names — verify they resolve first (step 5).
+- Keep every edit additive and reversible.

package/skills/kit-dev/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: kit-dev
+description: >
+  Fast local dev loop for claude-kit itself (the plugin source). start: worktree +
+  launch instructions for `claude --plugin-dir` (plugin loads live from disk, no cache, no
+  version bump). Iterate with /reload-plugins. ship: auto-bump semver + kit-task-pr-auto +
+  one-command update of the installed plugin.
+when_to_use: >
+  When modifying the kit itself — skills, agents, hooks, scripts, profiles in the
+  claude-kit-plugin source — and you want to test changes live without the
+  merge→bump→marketplace-update cycle. Not for consuming the kit (that's /kit-update).
+---
+
+# kit-dev — develop claude-kit without the publish cycle
+
+The kit's source of truth is the `claude-kit-plugin` package; the installed plugin comes from
+the marketplace (dedupes by version). This skill replaces the slow loop (merge → manual bump →
+marketplace update → plugin update) with a live local loop.
+
+## Subcommands
+
+`/kit-dev start <issue>` · `/kit-dev ship` · bare `/kit-dev` = print the loop + current state.
+
+## start — open the loop
+
+1. Worktree first, like all repo work: run the `/kit-task-start <N> --worktree` flow
+   (branch `task/<N>-<slug>` from the base branch). All kit edits happen in the worktree.
+2. Launch the dev session **from the worktree** with the plugin loaded live:
+
+```bash
+cd .claude/worktrees/<kind>+<N>-<slug>
+claude --plugin-dir "$PWD/packages/claude-kit-plugin"
+```
+
+- `--plugin-dir` loads the plugin directly from disk — no cache, no install, no version.
+- The dev-session plugin shadows the marketplace install for that session; the rest of
+  the sessions keep the stable installed kit.
+
+## iterate — the inner loop
+
+- Edit skills / agents / hooks / scripts in the plugin source.
+- In the dev session run `/reload-plugins` — picks up the edits in-session (skills, agents,
+  hooks, MCP). No restart needed; restart only if `/reload-plugins` misbehaves.
+- Project-level kit files (`.claude/skills/`, `scripts/`, rules) are ordinary repo files —
+  same worktree, no reload mechanics, new session reads them fresh.
+
+## ship — land it and update the installed kit
+
+1. `"${CLAUDE_PLUGIN_ROOT}/scripts/kit-bump-version.sh" beta` — bumps `version.json`,
+   `plugin.json`, `package.json`, and the marketplace manifest(s) in sync.
+   (`patch`/`minor`/explicit semver for releases — a clean release advances the `stable`
+   channel, a `-beta.N` build advances `beta`.) NEVER ship a kit change without the bump:
+   `/plugin update` dedupes by version and silently skips.
+2. Run the `/kit-task-pr-auto` flow — commit, push, PR (`Closes #N`), squash-merge to the base.
+3. Update the installed plugin (one command, in any session):
+
+```
+/plugin marketplace update claude-kit-marketplace
+/plugin update claude-kit@claude-kit-marketplace
+```
+
+## Rules
+
+- Worktree always — never edit the kit in the main checkout.
+- The semver in `plugin.json`/`version.json` is load-bearing: the session banner and `/kit-update`'s
+  changelog delta read it. Auto-bump on ship, never remove it.
+- The lockfile rule still applies if a kit change touches deps.

package/skills/kit-digest/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: kit-digest
+description: Pre-digest long inputs (video transcripts, CI logs, big files, web pages) with the LOCAL model (mlx_lm.server) so the Claude session reads a short digest + pointer instead of the full content — token saving on every long read.
+when_to_use: Before reading any long input into the session — a YouTube/video transcript, a CI failure log, a file or page over ~2k words. Especially "procesa este video/transcript/log". If the local server is down, the script says so — fall back to reading the original directly.
+---
+
+# kit-digest
+
+Plugin-direct skill — the script + local-model helper resolve from `${CLAUDE_PLUGIN_ROOT}`.
+
+## What it does
+
+Delegates to `${CLAUDE_PLUGIN_ROOT}/scripts/kit-digest.sh` — acquires the text (file, URL, or
+YouTube video via yt-dlp subtitles), chunks it (~2500 words), digests each chunk on the **local
+model** (`${CLAUDE_PLUGIN_ROOT}/scripts/lib/kit-local.sh` → mlx_lm.server, $0 API), merges, and
+prints a digest of at most ~1500 tokens plus a pointer to the original for selective deep-dives.
+
+## Execution
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/kit-digest.sh" <path|url> [--focus "<topic>"] [--lang es|en]
+```
+
+| Flag | Description |
+| --- | --- |
+| `--focus "<topic>"` | Prioritize content related to a topic (e.g. `--focus "claude-kit"`) |
+| `--lang es\|en` | Digest language (default `es`) |
+
+## Exit codes — the fallback contract
+
+| Code | Meaning | What Claude does |
+| --- | --- | --- |
+| 0 | Digest printed | Use the digest; read the original only for targeted deep-dives |
+| 2 | Local server down | Tell the user (start command is in stderr) and read the original directly — current behavior, no digest |
+| 1 | Input error (not found, no subs, empty) | Surface the error verbatim |
+
+## Rules
+
+- Never paste the full original into the session when the digest succeeded — the digest + pointer IS the deliverable of this skill.
+- The digest must keep concrete numbers, names and issue/PR refs; if it visibly lost a critical detail, deep-dive the original section instead of re-digesting blind.
+- Requires: `mlx_lm.server` running (see the `kit-local.sh` header), `yt-dlp` only for YouTube URLs.