ht-skills

Add a docs/architecture.html living system map to an existing repo — explores the codebase (entrypoints, data flow, CI/deploy wiring) and known failure modes (fix commits, closed bugs, CLAUDE.md gotchas), then writes a self-contained, dependency-free HTML architecture doc with an inline-SVG data-flow diagram, failure-modes table, and key-files list, filled in with the repo's real components. Use when the user wants to "add an architecture doc", "add a system map", "visualize the architecture", "add docs/architecture.html", or otherwise bring a visual architecture doc to a repo that doesn't have one. Detects an existing docs/architecture.html and won't overwrite without consent. New repos get the blank template automatically via /project-scaffold.

Audit one or more repos for deviation from this project's CI baseline — duplicate `push` triggers on develop, missing Playwright browser cache, missing workflow_dispatch or /rebuild, unexpected job names, a `claude-code-review.yml` that is absent, missing its draft gate, or missing its OAuth token secret. Use when the user wants to "audit CI", "check the CI baseline" (also "check for CI drift" — this skill's former name), "make sure the repos still match the baseline", "why did Actions minutes go back up", or is setting up a recurring/scheduled check across repos. Read-only by default — reports findings, never edits a repo unless explicitly asked to fix.

Add canonical AGENTS.md project instructions plus a thin CLAUDE.md adapter to an existing repo — detects the stack, selects a lean per-stack template, and preserves authored instructions. Use when the user asks for AGENTS.md, CLAUDE.md, agent-neutral project instructions, or Claude Code configuration. Refuses to overwrite authored instruction files without consent.

Add GitHub Actions to an existing repo — scaffolds the CI structure (a consolidated `checks` job running lint + format check + typecheck, plus a build job), wires release-please for automated versioning and changelogs from conventional commits, and drops a platform-agnostic deploy stub. Use when the user wants to "add CI", "set up GitHub Actions", "wire up release-please", "scaffold deploy workflow", or otherwise bring `.github/workflows/` to a project that doesn't have it yet. Detects existing workflows and extends them rather than replacing. Composes with `testing-init` (which owns the test jobs) and `project-scaffold` (which calls this internally for new projects).

Set up the main + develop (+ optional stage) branch model on an existing repo, push the new branches, apply branch protection, switch the GitHub default branch to develop, and write a CONTRIBUTING.md documenting the branch/PR/commit conventions. Use when the user wants to "set up gitflow", "add a develop branch", "configure branch protection", "add a CONTRIBUTING.md", "document our branching/PR conventions", "set up a PR-flow workflow", or otherwise bring this project's git workflow conventions to a repo that doesn't have them yet. Detects current branch state, idempotent — won't recreate branches that exist or stomp on existing protection rules without consent.

Use when work needs to continue somewhere the current conversation cannot follow — handing a project to another agent, another provider, a cloud session, a teammate, or to yourself next week. Trigger when the user says "write a handoff", "handoff doc", "hand this off", "write this up for another agent", "I'm running out of credits/context", "document where we are so someone else can pick it up", or invokes /handoff-doc. Produces one dated markdown document that lets a fresh reader resume without the transcript — current state, evidence, ordered next actions, settled decisions, and the traps that already cost time.

Add pre-commit hooks at the repo root to an existing project — installs the `pre-commit` package, generates a `.pre-commit-config.yaml` per stack (Python-only, Node-only, fullstack), activates the git hook, and runs `pre-commit autoupdate` so the user starts on current hook revisions. Use when the user wants to "add pre-commit", "set up pre-commit hooks", "add lint hooks", "set up commit hooks", or otherwise wire pre-commit into a repo that doesn't have it yet. Idempotent — won't overwrite existing config without asking.

Bootstrap a project repo with prescriptive defaults — Next.js or FastAPI, canonical AGENTS.md plus a Claude adapter, a documented git workflow, pre-commit, GitHub Actions CI, release-please, and a deploy stub. Use when a user asks to scaffold, bootstrap, initialize, or set up a new project or repository.

Bring the standard git + release workflow to a bare or framework-less repo in one step — git init + initial commit + private GitHub repo if needed, then gitflow branches + protection (via gitflow-init) and release-please + trimmed CI (via gh-actions-init). Use when the user wants to "set up the release workflow", "add gitflow + release-please", "bootstrap the git/release workflow on this repo", or set up branches + CI + releases on a repo that has no app framework. For framework apps (Next.js/FastAPI) use project-scaffold instead.

Use at the end of a work session to decide whether it is safe to close or archive the conversation. Trigger when the user says "can I archive this", "safe to archive?", "safe to close this out", "anything else before I archive this", "session cleanup", or invokes /session-cleanup. Runs a pre-archive checklist — is the stated work actually verified done, is the git state clean, is a retrospective warranted, are there durable learnings worth saving — then reports a definitive verdict and offers one action per gap. Reports and offers; it does not act without an explicit go. A recurring failure it exists to catch: retro notes or learnings dumped into chat to feel "durable" but never written anywhere that survives the archive.

Use after completing any substantial task — a feature, a bugfix, a multi-step debugging session, a deploy, a client deliverable — to generate a retrospective doc that captures failure signal (not just wins) alongside root causes, action items, and time calibration. Trigger when the user says "write a retro", "do a retrospective", "post-mortem", "retro on this", "what went wrong", "lessons learned", or invokes /task-retrospective. Proactively offer one whenever a task wrapped up with rework, a blown time estimate, a bug that shipped, or an assumption that turned out wrong. A retro that lists only wins is a FAILED retro — the "What went wrong (root causes)" section is mandatory, so dig until you find real failure signal.

Add a testing pipeline to an existing repo — installs runners (Vitest/Playwright/pytest), scaffolds passing test stubs, wires up `npm run test` / `pytest` / equivalent scripts, and optionally adds the matching CI workflow. Use when the user wants to "add tests," "set up a testing pipeline," "scaffold vitest/pytest/playwright," or otherwise bring a testing layer to a project that doesn't have one yet. Detects stack from `package.json` / `pyproject.toml`. Skips work that already exists (idempotent).