smorinlabs-harness

Build an interactive "codesign" decision page as one self-contained HTML file: the reader toggles choices (pick-one or pick-any), adds notes, and exports the decision as Markdown and JSON with stable IDs (sec-01, ch-01-a) so picks can be quoted in chat — "keep ch-01-a, swap ch-02-b" yields a diffable v2. Use when the user wants to choose between options and capture the decision: design directions, plan A vs B, prioritization, async option pages for a stakeholder. Triggers: codesign, co-design, decision page, pick from these, which should we, compare the options, prioritize these. ALWAYS confirms before generating — lists the UNANSWERED questions found in recent context, each with its ID and a recommendation, then waits for a yes; the gate fires even on explicit invocation with an argument. Answered questions are out of scope; if context is mostly settled material it offers html-explain instead. Styled by use-html-theme. NOT for signing macOS/iOS binaries (Apple's codesign).

Build a read-only "explainer" page as one self-contained HTML file — a rich explanation of settled material, where diagrams, annotated figures, charts, and small interactive widgets do work prose cannot. Authoring maps which parts are intrinsically hardest, budgets the page around them, then enriches ONLY where comprehension actually breaks. Use when an explanation should be a shareable PAGE not inline chat: "explain the design we just landed", "write up what the tests showed", "make an explainer for this spec", "deep dive on X as a page", explainer, walkthrough page, "explain this visually". Reads recent context and ALWAYS confirms the target before generating, even on explicit invocation with an argument. If context is mostly UNANSWERED questions it offers html-codesign instead (that answers questions; this explains — including a deep dive on one already resolved). Inline chat explanations are the `explain` skill; charts defer to dataviz when present. Pairs with use-html-theme.

Explain anything in a concrete-anchored style — succinct, just-enough context, always grounded in a real example. Use when the user invokes /explain, or asks in their own words: "explain X", "give me a before and after", "add more context on <finding/step/option>", "show examples of the options so I can decide", "what does this change get us", "what's the bigger picture here", "give me step by step instructions". A bare "explain" right after an explanation means "not enough to act on yet": diagnose the gap (bigger picture, clearer language, or a sharper example) and usually rewrite, not append; an argument steers the focus; a dissimilar target restarts fresh. Modes (inferred from the target; explicit argument wins): default, options (example per option + recommendation), deeper, steps (operator instructions). Not for manual testing steps (manual-test-guide) or whole-session recaps.

Whenever the user asks Claude to generate or restyle HTML — a page, artifact, mockup, dashboard, doc, status page, landing page, release-notes page, HTML email, or styled snippet — offer a small catalog of visual themes and apply the chosen one to all subsequent HTML in the session. v1 catalog: birchline (warm editorial), technical-minimal (docs-site neutral), high-contrast-dark (dashboard/terminal). Each theme is a self-contained folder of tokens, components, anti-patterns, and a worked example; only the chosen theme's files are read (progressive disclosure). The choice persists in session memory and can be saved per-project to `.claude/use-html-theme.local.md`. Overrides via natural language and `[theme: <name>]` / `[notheme]` inline flags; ask to preview or compare the themes to get a side-by-side catalog page. Do NOT activate for markdown, JSON, prose, or non-HTML code, or when the user said `[notheme]` or asked for no theme.

Walk a pile of open questions or undecided to-dos one at a time via the AskUserQuestion tool — smartest question first, just-enough context per item, and after EVERY answer re-evaluate the remaining pile (drop what became moot, reorder what changed, surface implied follow-ups). Sources it handles — mine open questions from the current conversation, read them from a document the user points at (PRD, design doc, notes), take a list given inline, or pull undecided items from task systems (tasks, PROJECTS.md). Decisions are recorded back at their source. Use when the user says "go through these one by one", "walk me through the open questions", "there's a bunch of to-dos, help me decide", "triage these decisions with me", or a doc/plan is blocked on several unanswered questions. Not for scoping a project idea (project-refine), not for batch shareable decision pages (html-codesign — offer it if they'd rather review async), and context style defers to the explain skill's anatomy.

Resolve a repo name to its local path(s) and identity facts — origin, default branch, checkout-vs-worktree kind, branch, dirty state, build tooling — with one fast config-bounded command instead of exploring the filesystem. Fire whenever a repo is referenced by bare name and its location isn't already established in this session — BEFORE running ls/find/glob over home or code directories to locate a repo, BEFORE gh repo view/list to identify an origin or enumerate org repos, and for "where is <repo>", "what repos do I have", "which org owns X", "is this a worktree", "what's the exact name to clone". Covers local multi-root scan plus a gh REST-first remote org fallback from user config. Not for searching file contents inside an already-located repo, and not for cloning or mutating anything — it only finds and describes.

Drive an open GitHub PR to merge by resolving every review thread. Waits (bounded) for AI reviewer bots (Claude, Codex, Greptile, Copilot) to comment, then triages each thread — validate the claim, verify by running code where possible, fix valid findings and push, refute invalid ones with a reasoned reply — every thread resolved either way. Cycles as fixes trigger new reviews, checks the PR title against repo conventions (CLAUDE.md, else Conventional Commits), then ends per mode: --auto (merge, no questions), --confirm (final gate; default), --ready (prep only); --deep adds an opt-in deep review. Quota-safe polling throughout (rate-limit preflight, 20s+ floor, bounded monitors). Use when the user says "merge this PR", "get PR #N merged", "resolve the PR comments", "address review feedback and merge", "close out this PR", "babysit the PR". Never closes a PR without merging; does not write the initial review (/code-review does) or fix failing CI (that is ci-audit).

Render actions only the READER can or will perform as a delineated, self-contained task block — a bounded frame (rail + rules) carrying what it completes, steps numbered with a stable tag, grouped by surface (terminal, browser, desktop/system UI, phone, physical world), each step titled by its outcome with the literal command or UI path below it and a ✓ verification line, closing with the immediate next move. Scales down to one line for a single step and up with a map and stop points for long sequences; re-renders in-flight processes across turns as a scoreboard; states errors as cause and fix. Fire on request — "format the manual steps", "what do I need to do by hand", "what's left for me" — and when composing any handoff with agent-impossible actions, manual verification, or work the user claimed. Decisions are not steps — anything needing the user's judgment is asked (question-walkthrough) before instructing. Canonical spec behind an always-on digest kept in global instructions.

Bootstraps the project-harness bundle by establishing its five skills, running a four-step idempotent setup on first use per repo, and routing project-state edits through the right sibling skill.

Reads PROJECTS.md and projects/ to surface a composite menu of in-progress projects, the next 2-3 lowest-ID unstarted projects, and the 2-3 most recently committed project files, then asks the user where to focus and points at the appropriate sibling skill or framework. Read-only — never edits PROJECTS.md or projects/.

Orient across the four factor-harness skills (using-factor-harness, factor-architect, factor-scan, factor-dedup) and route to the right one. factor-harness is the small skill set for two recurring code-quality activities: architecture-aware review/refactor and cross-implementation deduplication. Each workflow skill produces an inline spec that hands off to Superpowers writing-plans for the actual code changes. Use this skill when the user mentions architecture review, refactor opportunities, code scanning, bug hunting, or duplicated implementations — even if they don't name a specific factor-harness skill.

Orchestrates deep research at high-value moments and organizes the results for reuse. Use this skill whenever you are (1) making an architectural decision — choosing between libraries, algorithms, frameworks, or structural approaches; (2) kicking off a new project, major feature, or milestone where the problem domain has established best practices (billing, auth, caching, CLI design, etc.); (3) about to go deep on how a chosen library or technique works for a specific use case; or (4) hitting repeated errors with an unfamiliar API or pattern after a couple of ordinary web searches. Also use it when the user asks for deep research, thorough research, or research on options/best practices/approaches — and consult it during planning phases, before writing PRDs or implementation plans, even if the user doesn't say the word "research." Agents habitually under-research — a couple of shallow web searches at a decision point is usually a signal this skill should have fired.

Runs eleven drift checks (or a scoped subset) against PROJECTS.md and projects/ by dispatching one project-auditor subagent per check in parallel, then walks each finding interactively and asks before fixing. Defaults to focus mode — auditing only the candidate set most likely to hold drift (out-of-order, stragglers, recent active). Use --all for the full sweep. Each accepted fix is one revertable commit and is post-fix re-verified. Stateless — does not remember past skips.

Captures a project idea in at most four questions asked one at a time (the fourth is optional — open questions and notes), picks the next available P## from the local trunk (always max+1), and writes the idea stub from templates/project-idea.md plus the trunk row in a single atomic git commit. Refuses to scope or decompose — points at project-refine if depth is wanted.

Walks the user through one of three sub-modes (refine notes/references, scope an idea up to ready, or decompose into tasks) using one-question-at-a-time dialog. Promotion from idea ([?]) to ready ([ ]) requires explicit user confirmation. Dispatches project-researcher subagents in parallel when the user uses verbs like find / look up / research / investigate. Refuses to create new projects (project-add) or execute tasks (Superpowers).

Architectural review against precedent, conventions, and external good-pattern references. Two trigger contexts — pre-execution (review a Superpowers plan before code is written) or post-execution (review delivered code for refactor opportunities). Walks user through findings per-bucket. Produces an inline architectural review and refactor spec ready for Superpowers writing-plans. Use this whenever the user has just gotten a plan back, just shipped a feature, or wants an architectural review — even if they don't say "factor-architect" (phrases like "review this plan", "is this architecturally sound?", "any refactor opportunities?", "does this fit our patterns?", "look at recent commits" should all trigger).

Cross-implementation consolidation for N similar implementations. Walks comparator reports per-implementation, classifies divergences as intentional or accidental, proposes a unified design (or documents why divergence should stay). Produces an inline consolidation spec ready to feed to Superpowers writing-plans. Use this whenever the user has multiple files/functions/commands they suspect are duplicates — even if they don't say "factor-dedup" (phrases like "consolidate these", "these all look the same", "DRY this up", "extract common code", "shared abstraction" should all trigger).

Broad sweep over a code area surfacing bugs, quality issues, and architectural smells. Walks the user through findings one at a time. Produces an inline spec ready to feed to Superpowers writing-plans. Use this whenever the user wants to scan a directory, file set, or recently-changed code for issues — even if they don't say "factor-scan" by name (phrases like "any bugs in this?", "review this for quality", "audit these files", "what's wrong here?", "code health check" should all trigger).

Use when the user asks about "GitHub Actions", "CI", "fix CI", "fix GitHub actions", "actions broken", "check actions", "monitor actions", "actionlint", "pre-commit hooks", "are hooks running", "check if actions are passing", or any request to audit, fix, monitor, or troubleshoot CI/CD pipelines and pre-commit hooks.

Use when the user asks "how to manually test", "what are manual testing steps", "what commands to test", "how to test the latest features", "what to test", "what are the testing commands", or any request for manual testing instructions and validation steps for a project.

Use when the user asks to "update README", "sync README", "check README", "is README up to date", "are docs consistent", "does README match the code", or any request to verify or update README.md to match the current state of the codebase.

Use when the user asks "what version", "check version", "is version published", "version mismatch", "bump version", "what version is this project", "check if published", or any request to inspect, compare, or validate project versions across local files, git tags, and package registries.