huhhb

Use when bootstrapping a repository — greenfield or brownfield — into Uhstray's standard development conventions, OpenSpec, and the two-store memory setup. Idempotent and non-destructive: safe to re-run, never overwrites existing docs. Triggers on "repo kickstart", "bootstrap this repo", "set up our conventions", "conform this repo", "initialize plans/openspec/memory", "initialize this repo for openspec and memory", "set up two-store memory here", "index this repo and create its memory bank".

Use when checking or setting up the four-strata memory system on this machine and in the current project — "is my memory set up right", "memory onboarding", "set up memory", "check my memory setup", after a fresh machine/repo, when repo-kickstart or buhhdy's preflight reports memory degradation, or when .claude/memory / MemPalace / evolve looks misconfigured.

Use when any orchestrating agent's development workflow — buhhdy's Workflow 2 is the canonical caller — has open PRs that need driving from creation through merge and cleanup — the terminal step once PRs are open. Triggers on "shepherd this PR", "drive the PR to merge", "babysit the PRs", "monitor the PR to merge", and post-merge close-out (close linked issues, archive the change, remove the worktree, janitor stale branches in the orchestrator's own prefix (buhhdy/* canonical)). Also load to verify PR-lifecycle preconditions (branch protection, CodeRabbit) before shepherding.

Use when the user says "remember", "don't forget", "save that", "keep that in mind", "recall", "what do we know about", "look that up", or any request to persist or retrieve project knowledge — stores memories in .claude/memory/ using the Claude Code memory format, committed to git so the whole team shares context.

Use when starting new planning/research on a project or picking up development against an existing plan — buhhdy's two standard, repeatable sequences: Planning & Research (fresh problem to a validated plan — an OpenSpec change where the repo has adopted the conventions — plus issues) and Development (fanout, audit, docs, and pr-shepherd).

Reference skill for buhhdy's provider routing logic — the decision tree, model tier table, per-provider strengths, skill-to-provider affinity, and cross-review pairings. Load when reasoning about which provider to use and why, or when a task doesn't clearly match the main routing tree.

Use when a repo OPTS INTO Uhstray's plans/development + plans/architecture conventions — the store-registration setup an adopting repo runs once, the house openspec/config.yaml rules, and the archive-time ADR promotion into plans/architecture/. Triggers on "openspec conformance", "register the openspec store", "plans/ layout", "promote an ADR", "openspec store setup", "conform openspec to plans". The single source of truth repo-kickstart (adoption) and pr-shepherd (archive, on adopted repos) both call.

Use when the user EXPLICITLY requests product inception — "new product", "product inception", "new major initiative", "greenfield product planning" — or explicitly asks for a BMAD-style phase (product brief, PRD, product architecture) for a major initiative. Never inferred from task size — for a feature, change, or bug (even "use our full planning process"), use core-workflows Workflow 1 instead.

Use when a goal is big, vague, or dependency-heavy and you need to map every piece of context required before planning — "map the context", "what context do I need", "build a context graph/DAG", "what do I need to know before I can plan this", "discover the dependencies first"

Use when converting a Markdown file into a beautiful, print-ready PDF — reports, docs, specs, or exports with a styled cover page, running headers/footers, page numbers, tables, syntax-highlighted code, and mermaid diagrams.

Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification

Use when buhhdy's provider/model/auth facts need re-verifying — the operator says "run calibration refresh", the monthly refresh is due, a dispatch just failed on a bad or retired model ID, or a provider announced a model change. Covers model-ID drift, deprecation/shutdown dates, per-token pricing, auth/tier/billing status, and CLI/harness behavior claims going stale in buhhdy's `config.yaml` and `MODEL-MANIFEST.md`.

Use when turning a repeated, successful multi-step workflow from past sessions into a reusable overlay skill — distilling a proven procedure into a class-level skill proposal ("distill a skill from this", "turn this workflow into a skill", "make a skill from how I keep doing X", "extract a skill from my history"). Creates an eval-gated, human-approved proposal — never writes a skill directly. For auditing existing skills use evolve-skills; for session corrections use evolve-review.

Use when running evolve's learning pass over recent sessions — triaging captured observations into overlay patches, new overlays, repo-memory entries, or discards ("run the learning pass", "evolve review", "review session learnings", "turn recent sessions into skill updates") — or when approving proposals a headless review staged in pending/ ("approve evolve proposals", "review pending proposals"). For recalling what evolve already knows, use the evolve skill instead.

Verify an implementer's diff with an INDEPENDENT, different-vendor sub-agent (diff plus contract only), LOCALLY and BEFORE the PR is opened; turn blocking issues into fix-tasks and loop until clean — only then does the implementer open its PR.

Run independent subtasks in parallel — one git worktree and one implementation sub-agent per task, each cross-reviewed LOCALLY before it opens its own PR. buhhdy never merges; the human does.

Use when working with evolve's Honcho-backed cross-session memory — recalling what is known about the user or a skill ("what do you know about me", "check evolve memory", "what has evolve learned"), persisting a durable user fact across projects ("remember this everywhere", "remember this about me"), or deciding which memory stratum (Honcho, repo-memory, MemPalace, overlay skill) a piece of knowledge belongs in.

Delegate read-only investigation, debugging, audit, search, or code-understanding tasks to sub-agents; synthesize only from their structured reports.

Use when reviewing the skill library as a whole and driving the skill lifecycle — auditing every hub skill and overlay against usage telemetry, bench history, and lint debt to decide refine/merge/prune/create ("review the skill library", "skill lifecycle pass", "which skills need work", "audit our skills"), or when distilling a new skill from sessions that solved a task class without one ("distill a skill from this", "turn this workflow into a skill"). For session-centric learning (corrections, preferences), use evolve-review instead.

Use when a long working session should pause for a grounding checkpoint — fired by the huhhb grounding hook after the configured interval (default 2h) or on returning from a long break, or run manually to re-engage with in-flight work before it drifts. Triggers on "grounding", "/grounding", "grounding checkpoint", "ground the session", "are we still on track", "checkpoint the session". Opt-in via huhhb; off by default.

Use when understanding the whole skill ecosystem and how skills relate — inventorying every skill across tiers (repo / user / plugin), drawing relationships between them (overlaps, complements, composes-with, supersedes, gaps), recommending which to augment vs. build, avoiding duplicate skills, or promoting a user skill to the repository ("map the skills", "how do my skills relate", "which skills overlap", "what skill gaps exist", "recommend skill improvements", "promote this skill to the repo"). For one skill's health use evolve-skills; to create one workflow skill use evolve-distill.

Use when inspecting the health of evolve's learning loop — spool depth, deriver queue, injection-cache age, overlay confidence table, and pending proposals ("evolve status", "is evolve working", "memory loop health", "show overlay confidence", "why is my evolve context stale").

Use when starting a session that should continue prior work — phrases like "resume the session", "pick up where we left off", "continue from where we stopped", "where were we", "load the continuation file". Consumes the .claude/CONTINUE.md written by session-save: verifies it against the repo, re-hydrates context, briefs, then acts. Not for mid-session checkpoints (use grounding) or recalling stored facts (use repo-memory).

Use when ending, pausing, or running low on context in a working session and you want to resume cleanly later — phrases like "save our spot", "before I close this session", "pick this up tomorrow", "make a follow-up file", "so we can continue", "write a continuation doc", or when a session is about to compact/expire mid-task. Writes the continuation file consumed by session-resume. Not for mid-session checkpoints (use grounding) or storing standalone facts (use repo-memory).

Use when a large function, component, or call site needs decomposing into named single-purpose units — extract computation blocks, guard clauses, setup phases, UI subtrees, or bundled parameter groups, or move a function to a better module. Triggers on "strict refactor", "/strict-refactor", "extract function", "extract component", "break up this function", "split into smaller functions", "group these parameters". Changes structure only — no logic, no renames, no designed abstractions.

Use when reviewing code to replace redundant or verbose logic with a provably-equivalent simpler form — custom code that duplicates a stdlib/builtin or an existing project function, dead/no-op arguments, collapsible redundant expressions, duplicate inline logic that reimplements something already defined in the codebase. Triggers on "strict simplify", "/strict-simplify", "reduce redundant code". Does not restructure, rename, reformat, optimize, or fix bugs.

Mine a project directory or raw text into the memory nexus for future recall. Triggers on "mine this project", "index this directory", "add project to memory", "mine into memory".

Search the memory nexus for relevant team knowledge, decisions, or context. Triggers on "search memory", "find in memory", "look up in nexus", "what do we know about X".

Access, search, and manage the team memory nexus — mine projects, store context, and recall knowledge. Triggers on "remember this", "save to memory", "check memory", "what do we know about", "recall". Auto-triggers at session start to load context.

Show memory nexus statistics — drawer count, wings, rooms. Triggers on "memory status", "nexus stats", "how much is in memory", "what wings exist".

Use during implementation to narrate changes as they happen — activates for the session and explains each logical change, each completed plan task, and every change being committed, using brief prose plus simple ASCII diagrams. Triggers on "explain as you go", "narrate changes", "walk me through the changes", "explain what you're doing", and similar. Output is chat/CLI only — nothing is written to files.

Use when augmenting or explaining a plan, spec, design, or RFC document — enriches the document in place with decision criteria, cited source context, target-outcome framing, and prose-introduced mermaid diagrams. Triggers on "explain the plan", "add rationale", "why did we choose", "cite the sources", "augment this spec", "add diagrams to the design", and similar. Composes with writing-plans rather than replacing it — writing-plans authors the plan; this skill makes it self-explaining.

Compress natural language memory files (CLAUDE.md, todos, preferences) into caveman format to save input tokens. Preserves all technical substance, code, URLs, and structure. Compressed version overwrites the original file. Human-readable backup saved as FILE.original.md. Trigger: /caveman-compress FILEPATH or "compress memory file"

Socratic teaching mode — Sensei. Guides users to solutions without ever writing new code. Describes approaches, names relevant APIs/functions, provides documentation links, explains errors in plain language, and asks questions that lead the user to the answer themselves. Use when user says "training mode", "sensei mode", "teach me mode", "guide me through this", "teacher mode", "help me learn", "I want to learn", "no code just explain", or invokes /training. Also triggers when user says "explain without doing" or "don't write it, teach me".

You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.

Use when setting up Claude Code for the first time, configuring auto mode, enabling agent teams, or when user says "set up Claude", "configure my assistant", "onboard me", or "enable auto mode"

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

Use when creating new skills, editing existing skills, or verifying skills work before deployment