kubes-mode-v2

Files (19)

• SKILL.md
• bug-fix.md · playbooks/
• feature.md · playbooks/
• hillclimb.md · playbooks/
• investigation.md · playbooks/
• multi-phase-plan.md · playbooks/
• pause-safely.md · playbooks/
• perf-issue.md · playbooks/
• prototype.md · playbooks/
• refactoring.md · playbooks/
• runtime-forensics.md · playbooks/
• worktree-cleanup.md · playbooks/
• context-window.md · principles/
• enforce-lessons.md · principles/
• explain-the-number.md · principles/
• fix-root-causes.md · principles/
• prove-it-works.md · principles/
• check-plan.mjs · scripts/
• worktree-audit.sh · scripts/

SKILL.md (first lines)

# kubes mode

A router. Match the task, open only the files it needs, and keep ceremony proportional to the task.

## Precedence and scope

- The user's explicit instructions override this skill. Harness and safety rules override both.
- Do the task that was asked. Extra scope (refactors, guardrails, tests, retries) needs the user's agreement or a clear link to the task. Report adjacent problems instead of fixing them.
- If this skill makes you pause, ask, or leave work unfinished, name the rule and file that caused it, so the user can fix the skill.
- A broken or wrong skill mid-task: say what is wrong, work around it in the open, and propose the fix separately. Do not edit the skill inside unrelated work.
- Rigor applies to evidence, not to process. Do not add defensive gates, lockboxes, frozen trials, attempt budgets, or default-deny blocks the user did not ask for. When a run or design keeps fighting you, ask whether you are overcomplicating it and take the simpler mechanism.

## Questions and autonomy

Before you ask the user a "which approach" or "what should this do" question, classify it:

- **A fact you can observe** (behavior, output, timing, perf, layout): find out. Read the code, run it, or sketch it with `playbooks/prototype.md`. In a read-only investigation, answer from evidence instead of building a sketch.
- **An expensive direction** (paid compute, multi-day work, a new language or stack): research first, then give the cost, the benefit, and one recommendation. Build after the user says to proceed.
- **A material design decision the user must weigh in on**: use the `grill` skill, after you have done the authorized work that makes the options concrete. Under an explicit autonomy grant that covers the decision, choose and report the choice with its reason instead.
- **A product or preference call** no experiment can settle: ask, with your recommendation and its reason.

Autonomy:

- **Proceed** on reversible local work within the task: reads, edits, builds, tests, branches, worktrees, scratch prototypes. Deleting code made obsolete by the change is part of the change. Committing and pushing verified checkpoints to the current feature or PR branch also counts.
- **Needs authority from the task or the user**: anything else with an external effect, such as pushing to `main`, opening or merging PRs, posting comments, updating tickets, sending messages, and paid model calls, VMs, sandboxes, or uploads. Record the approval the user gave for paid work, and never re-run a paid result that already succeeded.
- **Always pause** for irreversible actions, unless the user authorized that exact action and target: force-push to shared branches, deploys, deleting user data or untracked files, messages to customers. A named gate from the user also pauses.
- **Session overrides** ("don't stop", "going to bed", "run until done") change persistence, not permission. Keep working on everything that does not need the user. Under an explicit full-autonomy grant, decide calls the grant covers and report each decision with its reason.
- **No is an acceptable answer.** When asked whether to do something or shown an approach, give your real judgment. Push back, decline, or say it does not earn its place. A recommendation is a judgment, not a validation.

## Skill routes

- Data shape, boundaries, file and module structure → `code-structure-and-modularity`.
- Simplify working code, or size a diff → `code-simplification`. Match the solution to the task: a field change is not a redesign.
- Review a diff or PR → `code-review-and-quality`.
- Contested design or open decisions that need the user's input, or the user asks for it → `grill`.
- Upstream source or library internals → `github-librarian`.
- External research → Exa and Firecrawl (Alexandria), reading each tool's skill before the first query. Run several rounds and vary the search type and depth per area. If a tool needs a login, help the user log in and retry instead of dropping the source. Keep internal results and strategy details out of queries.
- Reply and prose style → `personality`. This skill sets no style rules.
- Other skills may live in the non-symlinked dotfiles repo at `~/git/dotfiles/skills/`.

## Code and verification

- Stateful logic, branching, or a shape repeated across files: name the data shape and its organizing structure before writing logic. Trivial edits skip this.
- Every changed line traces to the request. Match the file's existing style. No speculative abstractions, config, or error handling for impossible states.
- Reproduce a bug before fixing it, and re-run the failing case live after the fix. When re-running a failed batch, retry one case first, then the rest.
- Tests exercise real behavior through public entry points, real Git, and real binaries. No tests of mocks, source text, wording, or defaults.
- Fail closed: missing, malformed, or unknown evidence is a failure or "unknown", never a pass or zero.
- Refer to credentials by env var name. Do not read `.env` files or print keys.
- Verify on the real surface with the smallest check that fits the risk. Use the project's `verify-*` skill or documented verification path when one exists. Otherwise drive the surface yourself: run the CLI, open the page, call the API. Do not exercise a live surface that writes real data or has external effects without authority. See `principles/prove-it-works.md`.

## Subagents

- Fan out wide. Run independent slices in parallel, as many as the account allows. Use tagged peer models as co-workers that trade hypotheses, own workstreams, and cross-check facts, not only as reviewers. If a tagged model is unavailable, report it instead of substituting another.
- Each brief names the files the subagent owns, the files it must not touch, its non-goals, and its acceptance criteria. Sibling subagents that share an interface coordinate with each other directly.
- Subagents do not run the test suite, builds, linters, or formatters, and do not touch Git. Throwaway repro scripts are fine. They return changed files, a runnable smoke or repro command, `file:line` citations, and open unknowns.
- The parent integrates, runs the full verification once, and commits with `github-yeet`. Send corrections to a running subagent instead of redoing its work afterward.
- You own every delegate's output: review the diff, run the final verification, and write your own summary. A second opinion from a different model is useful when it challenges assumptions with evidence; agreement alone is not verification.

## Git and PRs

- Every commit, push, and PR goes through `github-yeet`. Do not hand-roll `git commit`, `git push`, or `gh pr create`. It sets conventional branch, commit, and PR names, stages only this session's files, and updates an existing PR in place.
- Commit and push each verified checkpoint on the current feature or PR branch without being asked, including periodically during long runs. For a checkpoint, run `github-yeet` through the push step and stop before the PR steps. Opening a PR, pushing to `main`, or merging still needs the request. "Commit this" does not mean "open a PR".
- Split commits into small logical units. Never `git add .`.
- Before opening or updating a PR, run `/code-review` on the diff and fix the valid findings.
- After pushing, watch CI and fix failures until it is green. Report done only when CI is green or the failure is outside the change, and say which.
- When syncing with `main`, merge `origin/main` and resolve conflicts so recent changes on both sides keep their intended behavior.
- **PR status** ("check on PR X", "anything outstanding?"): read-only. Fetch CI state and review comments, assess each for validity, and report a triage table: fix, dismiss with reason, or ask.
- **Address or fix PR comments**: fetch the comments on this branch's PR and assess their validity. Trust but verify: investigate each one rather than treating it as fact. Fix the fair and valid ones, commit and push, then reply to and resolve the threads you actioned. Follow `github-yeet` (PR comments and autofix). This does not authorize a new PR or a merge.
- **Babysit, watch, or autofix a PR** until it is ready → `github-yeet` (PR comments and autofix). It repeats across CI runs and review rounds.

## Long or unattended work

For long or multi-phase work, or work the user will review later:

- Write a completion predicate first: what must be true for the task to be done, and how to check it.
- Keep the predicate, remaining steps, and material decisions (choice, reason, evidence) in the harness's todo state or an existing plan file, so the work can resume without the full conversation. Create a decision-log file only for unattended or audit-worthy runs, keep it local, and commit it only when asked.
- A status update or a finished phase is not a stopping point. Continue independent work until the predicate holds. Stop on an explicit pause or stop, a named gate, or a concrete blocker that prevents all remaining work. Then say exactly what is blocked and why.
- Planned multi-PR programs use `playbooks/multi-phase-plan.md`.

## Playbooks

Match the task to one playbook and open its file. For multi-step work, put its steps in your todo list. Steps marked **Gate.** are required; skip one only with a stated reason in the reply. Small tasks can follow a playbook without a todo list.

- **Investigation.** Read-only question: how does X work, why is Y built this way, should we do X or Y. `playbooks/investigation.md`.
- **Bug fix.** Reproduce, root-cause, and fix a reported defect with runtime evidence. `playbooks/bug-fix.md`.
- **Feature.** New or changed behavior, built from a named data shape. `playbooks/feature.md`.
- **Refactoring.** Behavior-preserving change to structure (rename, extract, inline, dedupe, move). `playbooks/refactoring.md`.
- **Prototype.** Throwaway sketch to settle a design or behavioral question by observation. `playbooks/prototype.md`.
- **Perf issue.** A measured slowness to trace and improve against a baseline. `playbooks/perf-issue.md`.
- **Hillclimb.** Sustained improvement of one metric against a target, one measured change at a time. `playbooks/hillclimb.md`.
- **Runtime forensics.** Diagnose a live symptom (leak, CPU spin, glitch) from instrumentation. Diagnosis, not a fix. `playbooks/runtime-forensics.md`.
- **Pause safely.** Suspend in-flight work so it can resume: going offline, restart, or close to compaction. `playbooks/pause-safely.md`.
- **Multi-phase plan.** Work that spans phases or stacked PRs. `playbooks/multi-phase-plan.md`.
- **Worktree cleanup.** Reclaim disk by pruning merged or abandoned git worktrees. `playbooks/worktree-cleanup.md`.

No playbook fits: write a short plan (goal, steps, how each step is checked) and follow it.

## Principles

Read the file in full before you apply a principle.

- `principles/prove-it-works.md`. Before you call any task done.
- `principles/fix-root-causes.md`. Debugging, perf regressions, runtime symptoms.
- `principles/explain-the-number.md`. Before you trust, report, or act on a perf or eval number used to compare options or justify a change.
- `principles/context-window.md`. Large outputs, long files, repeated reads, fan-out.
- `principles/enforce-lessons.md`. The same correction comes up a second time.

## Evidence and handoff

- Ground material claims. Say which are measured, which are inferred, and which are guesses. A prediction or an unobserved cause is a guess.
- Never fabricate a link, citation, command output, or transcript reference. Link only what you produced or read.
- Do not hand the user a check you could run yourself and are allowed to run.
- Terse is not a reason to drop content: keep tradeoffs, choices, open decisions, and what was not verified.
- For a change, say who notices it (an end user, a caller of the library) and what the next maintainer inherits.
- Status reports are tables, broken down along the axes the user names. A comparison ends with one recommendation.
- Long research goes in a dated repo doc (`docs/research/YYYY-MM-DD--slug.md`, or the project's existing docs folder). The reply gives the summary and the path.
- A decision or lesson future agents need goes in a brief note in `AGENTS.md` or next to the related doc.

## Comments

From ahstn/dotfiles, MIT.

More from ahstn/dotfiles