genkovich

Prepare and verify the repository files required to deploy this Next.js project to one Ubuntu VPS with Docker Compose and a GitHub self-hosted runner. Use when creating or reviewing Dockerfile.production, compose.vps.yml, the health route, persistent SQLite storage, or deploy-vps.yml before a VPS release.

Decide and apply the next semver for a release. Triggers on "bump the version", "what version is next", "/bump-version", "простав версію", "яка наступна версія". Reads the next number from the deterministic scripts/next-version.sh (NEVER guesses it), explains in plain language WHICH part moved and why (e.g. "MINOR, because a feat landed: filter notes by tag"), edits the version line in pyproject.toml, and proposes the matching `git tag vX.Y.Z`. The number is decided by a rule; the agent explains and applies — the human confirms the tag. Never pushes a tag itself.

Find and fix where docs/api.md fell behind the code. Triggers on "check for doc drift", "is the API doc up to date", "/check-docs-drift", "перевір дрейф документації", "docs drift". Runs the deterministic scripts/check-docs-drift.py (parses the public NoteBook methods with ast, compares to what docs/api.md documents — NO LLM finds the gap), reports the drift, and PROPOSES the doc edit that closes it. The gap is found by parsing; the agent writes the missing documentation in the doc's existing style. Edits only docs/; never commits or pushes.

Turn a repeated mistake into a durable, path-scoped rule in .claude/rules/. Triggers on "codify this rule", "make a rule so this doesn't happen again", "/codify-rule", "закодифікуй правило", "петля помилка-правило". Use only when the same mistake showed up TWICE (twice = a pattern, once = noise). Names the wrong shape and the right shape with one short example of each, scopes the rule to the paths that matter, and leaves the edit in the working tree so the next agent on this repo inherits the fix. Edits only .claude/rules/; never commits or pushes.

Curate the [Unreleased] section of docs/CHANGELOG.md from git history. Triggers on "curate the changelog", "update the changelog", "/curate-changelog", "онови changelog", "курування журналу". Reads git log since the last tag, FILTERS out what a reader never feels (test/ci/chore/merge), GROUPS commits about one feature into one bullet, and REWRITES technical subjects into plain language under the six Keep a Changelog categories (Added/Changed/Deprecated/ Removed/Fixed/Security). The result must have FEWER lines than the raw log — that is the proof of curation, not a dump. Leaves the edit in the working tree; never commits or pushes.

Draft partner-facing release notes from the same commits as the changelog. Triggers on "draft release notes", "release notes for the next version", "/release-notes", "нотатки релізу", "release notes партнеру". Same input as curate-changelog, different audience and tone: a short, benefit-first narrative for a user or partner — "what's new for you" — not a categorized engineer's list. Keeps only changes a user actually notices; drops internal refactors and tooling. Prints the notes to the chat to seed a GitHub Release description or a partner announcement. Writes no file.

Run the whole local release pipeline in order, stopping at each human gate. Triggers on "run the release", "prepare a release", "/release", "зроби реліз", "підготуй реліз". Drives the four stages back to back — bump-version → curate-changelog → release-notes → check-docs-drift — pausing after each so the human reviews the diff before the next stage. Prepares everything in the working tree; never tags, commits, or pushes. The tag push (which fires CI) stays the human's action.

Реалізувати задачу за ДЕТЕРМІНОВАНИМ гейтом — ганяти `node --test` і НЕ казати DONE, поки тести червоні; вставити вивід як доказ. Порт 7.6 verify-gate під стек node:test.

Use to capture or update domain terms in CONTEXT.md before their meaning drifts — whenever a fuzzy word shows up in an interview, spec, or review and you want one canonical definition plus a NOT-reference so a homonym can't bite you in six months. Triggers on "add term {X}", "what is {X} in our domain", "add to CONTEXT", "fix the glossary", "define {X}", "/sdd:glossary {term}", "додай термін", "онови глосарій", "що означає {X}". Two-level contract: repo-root CONTEXT.md holds project-wide terms, docs/features/{slug}/CONTEXT.md holds feature-scoped ones; readers read both and the per-feature entry wins. Lazy-bootstraps the target from a template, checks BOTH levels for a conflicting existing entry, asks for a one-sentence definition + the concept it's confused with, and appends one line to ## Glossary. Skip generic tech words (HTTP, queue, cache) — those are not domain terms. Output: created/edited CONTEXT.md. Runs anytime, no input gate; specify, clarify, design and api read its ## Glossary as the canonical so

Use to derive the API contract for a feature — an OpenAPI 3.1 document at docs/features/{slug}/contracts/openapi.yaml plus a drift/sync report (and an events doc when the feature has async flows). Triggers on "api for {slug}", "openapi for {slug}", "API contract for {slug}", "lock the interface for {slug}", "events for {slug}", "/sdd:api {slug}", "контракт API для {slug}", "OpenAPI для {slug}", "опиши ендпоінти". The contract is never hand-written: it is a derived function of data-model.md (typed fields + constraints), the sad.md §6 sequence diagrams (error branches, async actors), and spec.md acceptance criteria. Runs an inline drift check (does the contract match the model and the sequences?) and a reconcile mode. Hard-refuse if data-model.md is missing AND the feature changes the schema → run `data-model {slug}` first; on a legal no-schema-change skip it derives from the existing schema instead.

Use to run an ambiguity sweep over a written spec.md and close every under-specified point before planning or design proceeds — so two engineers can't reasonably build different things from the same spec. Triggers on "clarify {slug}", "find ambiguities in {slug}", "is the spec ready", "sharpen the spec", "/sdd:clarify {slug}", "прояснити специфікацію", "знайди неоднозначності {slug}", "чи готова специфікація". Re-reads the spec, dispatches a clean-context devil's-advocate subagent to list where the spec forks, then for each ambiguity runs AskUserQuestion to RESOLVE it (tighten §1/§5/§6 in place) or DEFER it (→ §8 Open questions with owner+due). Output: an updated docs/features/{slug}/spec.md with every ambiguity resolved or deferred — none dangling. Hard-refuse if spec.md is missing.

Use to design the data model AND generate the actual forward + rollback migrations in one pass — shippable SQL, not a plan. Triggers on "data model for {slug}", "schema for {slug}", "generate migrations for {slug}", "DB design + migration", "/sdd:data-model {slug}", "модель даних для {slug}", "схема для {slug}", "згенеруй міграції". Reads spec.md §5 + sad.md §5 building blocks + the §6 sequence diagrams, then writes docs/features/{slug}/data-model.md plus paired *.up.sql / *.down.sql migrations STAGED under docs/features/{slug}/migrations/ (NOT the live migrations/ tree — implement promotes them when the feature is actually built) and an audit report. Greenfield-first; brownfield delta via --mode brownfield; drift-only via --drift-only. Hard-refuses if spec.md or sad.md is missing. Stack-agnostic: detects and FOLLOWS the repo's DB + migration conventions and domain layer — it imposes no DB philosophy and writes no rules file.

Use to record a post-hoc or asynchronous architecture decision as a MADR ADR when it was NOT captured during the synchronous design pass — a choice made in code, in a chat, on a whiteboard, or one a tasks/review gate flagged as missing. Triggers on "ADR for {decision}", "adr for {slug}", "document the decision on {topic}", "lock in the decision about {X}", "MADR for {topic}", "/sdd:decide-adr {slug} {title}", "створи ADR для рішення", "задокументуй рішення", "ADR на {тему}". Confirms the decision is ADR-worthy via the blast-radius gate, picks the next 4-digit number, copies design's MADR template, and fills context / drivers / considered options / outcome / honest consequences. Supports a Proposed → Accepted review flow. Output: docs/features/{slug}/adr/NNNN-{title}.md. For decisions made live with the user, use `design` — it spawns ADRs inline (Accepted).

Use to produce a Software Architecture Document for a feature — Arc42 12 sections + C4 L1/L2 inline + ADRs spawned on a blast-radius gate — once spec.md exists. Triggers on "design {slug}", "architecture for {slug}", "SAD for {slug}", "arc42 for {slug}", "C4 context+container for {slug}", "/sdd:design {slug}", "спроектуй архітектуру {slug}", "SAD для {slug}", "архітектурний документ {slug}". Drafts §1–§12 in-memory, batch-validates each section Socratically (4-state machine), spawns an ADR only when a decision crosses the blast-radius threshold (irreversible / multi-module / has legitimate alternatives), writes each resolved section + its ADRs atomically, then runs a clean-context critic before finalizing. Brownfield: dispatches an Explore subagent to map the repo first. Hard-refuse if spec.md is missing; CONTEXT.md is optional (when present its Glossary is canonical).

Use to fix a reported bug spec-first: reproduce it, trace the symptom to the owning feature's acceptance criteria, pin it with a failing (RED) test, apply the minimal GREEN fix through the same per-task gate implement uses, then patch the spec so the bug class can't silently return. Triggers on "fix {bug}", "fix the bug in {slug}", "bug in {feature}", "/sdd:fix {slug}", "regression in {slug}", "полагодь баг", "виправ багу", "регресія в {slug}", "чому зламалось". Triage is three-way: AC exists and is violated (regression) / AC is ambiguous (spec-bug — patch the wording) / no AC covers it (gap — add one, marked added-by-fix). Works on a repo with no specs at all (soft mode — code-first, recommends survey after). Writes a fix record under docs/features/{slug}/_fixes/ and commits with an SDD-Fix trailer.

Use to implement a feature from its tasks.json with test-driven development — writes a failing test first, makes it pass, refactors, gates, and commits per task. Triggers on "implement {slug}", "build {slug}", "TDD {slug}", "code up the tasks for {slug}", "/sdd:implement {slug}", "імплементуй {slug}", "реалізуй фічу {slug}", "напиши код за задачами". Reads docs/features/{slug}/tasks.json + the upstream artifacts, detects the repo's test/lint/vet commands stack-agnostically, builds a dependency DAG, and runs one of three modes — sequential single-agent TDD, an agent team (TeamCreate), or a dynamic Workflow — chosen from settings + DAG shape with graceful fallback. Hard-refuses if tasks.json is missing.

Curate the [Unreleased] section of docs/CHANGELOG.md from git history. Triggers on "curate the changelog", "update the changelog", "/gen-changelog", "онови changelog", "курування журналу". Reads git log since the last tag, FILTERS out what a reader never feels (test/ci/chore/merge), GROUPS commits about one feature into one bullet, and REWRITES technical subjects into plain language under the six Keep a Changelog categories (Added/Changed/Deprecated/ Removed/Fixed/Security). The result must have FEWER lines than the raw log — that is the proof of curation, not a dump. Leaves the edit in the working tree; never commits or pushes.

Draft and save partner-facing release notes from the same commits as the changelog. Triggers on "draft release notes", "release notes for the next version", "/release-notes", "нотатки релізу", "release notes партнеру". Same input as gen-changelog, different audience and tone: a short, benefit-first narrative for a user or partner — "what's new for you" — not a categorized engineer's list. Keeps only changes a user actually notices; drops internal refactors and tooling. Saves the notes to docs/release-notes/vX.Y.Z.md (the version comes from package.json) and echoes them in the chat, to seed a GitHub Release description or a partner announcement.

Announce a finished release to the team Telegram channel. Triggers on "announce the release on Telegram", "post the release notes to Telegram", "/announce-telegram", "анонсуй реліз у телеграм", "оголоси реліз". Reads the saved partner notes (docs/release-notes/vX.Y.Z.md), shows the EXACT message and the EXACT target chat, and waits for an explicit yes before sending via the Telegram Bot API (TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID). This is an OUTBOUND step — once sent, the message is public to the channel and cannot be unsent. It never decides on its own to announce.

Decide and apply the next semver for a release. Triggers on "bump the version", "what version is next", "/bump-version", "простав версію", "яка наступна версія". Reads the next number from the deterministic scripts/next-version.sh (NEVER guesses it), explains in plain language WHICH part moved and why (e.g. "MINOR, because a feat landed: filter memes by tag"), edits the version field in package.json, and proposes the matching `git tag vX.Y.Z`. The number is decided by a rule; the agent explains and applies — the human confirms the tag. Never pushes a tag itself.

Generate the user-facing guide for this release, with real screenshots. Triggers on "generate the user docs", "write the user guide", "/generate-user-docs", "згенеруй документацію", "користувацька документація". Runs the deterministic scripts/capture-screenshots.mjs (Playwright — NO LLM renders the picture) to shoot the app's key screens into docs/user-guide/img/, then WRITES the guide pages under docs/user-guide/*.md, embedding those shots. The screenshotter is the rule; the agent writes the words around it. This runs as the second stage of /release: it prepares docs/user-guide/** in the working tree; /release commits it into the one release PR. It never commits, pushes, or publishes to Redmine itself.

Publish the release's user guide to the Redmine wiki. Triggers on "publish the docs to Redmine", "push the user guide to Redmine", "/publish-redmine", "опублікуй документацію в redmine", "виклади в redmine". This is the LOCAL MIRROR of the merge gate's Redmine step — in the real flow CI publishes on the release-PR merge; run this to rehearse the same publish from your machine. Reads docs/user-guide/*.md, shows the EXACT pages and the EXACT Redmine target, and waits for an explicit yes before PUTting each page to the wiki via the REST API (REDMINE_URL, REDMINE_API_KEY, REDMINE_PROJECT). Outbound and terminal: it publishes, it does not commit or push.

Prepare a release locally and open the release PR. Triggers on "run the release", "prepare a release", "/release", "зроби реліз", "підготуй реліз". Does the two steps that need a human and a running app: bumps the version (bump-version) and generates the user guide with real screenshots (generate-user-docs, against your locally running app — CI can't boot it). Then commits both, pushes the branch, and opens ONE pull request. Merging that PR is the gate: CI writes the changelog and release notes, tags, publishes the GitHub Release, announces on Telegram, and publishes the guide to the Redmine wiki. This skill never writes the changelog or notes, never tags, and never sends anything outbound — the merge does all of that.

Turn a repeated mistake into a durable, path-scoped rule in .claude/rules/. Triggers on "codify this rule", "make a rule so this doesn't happen again", "/codify-rule", "закодифікуй правило", "петля помилка-правило". Use only when the same mistake showed up TWICE (twice = a pattern, once = noise). Names the wrong shape and the right shape with one short example of each, scopes the rule to the paths that matter, and leaves the edit in the working tree so the next agent on this repo inherits the fix. Edits only .claude/rules/; never commits or pushes.

Use to implement a feature from its tasks.json with test-driven development — writes a failing test first, makes it pass, refactors, gates, and commits per task. Triggers on "implement {slug}", "build {slug}", "TDD {slug}", "code up the tasks for {slug}", "/sdd:implement {slug}", "імплементуй {slug}", "реалізуй фічу {slug}", "напиши код за задачами". Reads docs/features/{slug}/tasks.json + the upstream artifacts, builds a dependency DAG, and drives each task through a strict TDD cycle against the repo's test gate (`npm run test:fast`) — sequential by default, optionally fanning the three subagents out over a large DAG. Hard-refuses if tasks.json is missing.

Use to implement a feature from its tasks.json with test-driven development — writes a failing test first, makes it pass, refactors, gates, and commits per task. Triggers on "implement {slug}", "build {slug}", "TDD {slug}", "code up the tasks for {slug}", "/implement {slug}", "імплементуй {slug}", "реалізуй фічу {slug}", "напиши код за задачами". Reads docs/features/{slug}/tasks.json + the upstream artifacts, builds a dependency DAG, and drives each task through a strict TDD cycle against the repo's test gate (`npm run test:fast`) — sequential by default, optionally fanning the three subagents out over a large DAG. Hard-refuses if tasks.json is missing.

Implement a feature from its tasks.json with test-driven development — write a failing test first, make it pass, refactor, gate, commit per task. Triggers on "implement {slug}", "build {slug}", "TDD {slug}", "code up the tasks for {slug}", "/sdd:implement {slug}", "імплементуй {slug}", "реалізуй фічу {slug}", "напиши код за задачами". Reads docs/features/{slug}/tasks.json + upstream artifacts, builds a dependency DAG, and drives each task through a strict TDD cycle against the repo's test gate (`npm run test:fast`) — sequential by default, optionally fanning the three subagents over a large DAG. Hard-refuses if tasks.json is missing.

Use to implement a feature from its tasks.json with test-driven development — writes a failing test first, makes it pass, refactors, gates, and commits per task. Triggers on "implement {slug}", "build {slug}", "TDD {slug}", "code up the tasks for {slug}", "/sdd:implement {slug}", "імплементуй {slug}", "реалізуй фічу {slug}", "напиши код за задачами". Reads docs/features/{slug}/tasks.json + upstream artifacts, builds a dependency DAG, and drives each task through a strict TDD cycle against the repo's test gate (`npm run test:fast`) — sequential by default, optionally fanning the three subagents over a large DAG. Hard-refuses if tasks.json is missing.

Use when the user wants to drop a source into the LLM Wiki inbox WITHOUT parsing it yet. Trigger phrases: "wiki:inbox <url|path>", "inbox this", "drop in inbox", "save to wiki later", "wiki: queue <url>", or when the user pastes a URL/file and says "for later". Stages the input in raw/_inbox/ so the wiki:parse skill (or the cron-ingest launchd job) can process it asynchronously. This skill does NOT call defuddle/yt-dlp/whisper — it only stages. Heavy parsing happens later.

Use when the user invokes LLM Wiki lint workflow — explicitly via "wiki:lint", "wiki: lint", "перевір wiki", "audit the wiki", or similar consistency-check requests. Scans entities/, concepts/, and comparisons/ for contradictions, stale pages, orphans, missing cross-references, and data gaps. Writes findings into a fresh questions/lint-YYYY-MM-DD.md and appends a log entry. Recognizes the wiki by a CLAUDE.md with `type: schema, scope: wiki` and follows the lint protocol from there.

Use when the user invokes LLM Wiki parse workflow — explicitly via "wiki:parse", "parse this", "parse this folder", "wiki: parse <path|url>", drops a YouTube link, or when a new file is dropped into a wiki's raw/_inbox/. Handles four input kinds: single file, folder (batch), generic URL (defuddle clip), or YouTube URL (yt-dlp transcript + optional whisper). Processes each source into the wiki: creates sources/<slug>.md summary, updates 10-15 entities/concepts with citations, appends a log entry. Recognizes the target wiki by a CLAUDE.md with `type: schema, scope: wiki` frontmatter. Reads that CLAUDE.md for the authoritative ingest protocol before acting.

Use when the user invokes LLM Wiki query workflow — explicitly via "wiki:query", "wiki: <question>", "що каже wiki про X", "знайди в wiki", "ask the wiki", or similar retrieve-and-synthesize requests against an LLM Wiki. Performs MCP qmd search across the wiki collection, reads the top-N results, and returns a synthesis with inline wikilink citations. Optionally proposes a filer-back into comparisons/ or questions/. Recognizes the wiki by a CLAUDE.md with `type: schema, scope: wiki` frontmatter and follows the query protocol from that file.

Use when validating that a service is ready to deploy. Triggers on "ready to deploy", "pre-deploy check", "can we ship", "deploy validation".

Use when reviewing a pull request to enforce team conventions. Triggers on "review this PR", "check the PR", "code review", "PR review checklist".

Use when auditing a branch for security issues before push or release. Triggers on "security scan", "secret scan", "pre-push check", "audit this diff", "check for leaked credentials".

Review code and diffs without changing files. Use when asked for a code review, diff review, bug or regression scan, or a merge-readiness verdict where the expected output is findings rather than fixes.

Review code and diffs without changing files. Use when asked for a code review, diff review, bug or regression scan, or a merge-readiness verdict where the expected output is findings rather than fixes.

Review code and immediately fix every issue you find.

Use when the user wants to BUILD or AUDIT an HTML presentation deck — workshop (hands-on, terminal demos), lecture (live educational), or talk (conference keynote). Three modes: (1) spec mode — a .planning/deck-spec.md exists (written by deck-plan) → scaffold + per-slide Socratic generation; (2) audit mode — an existing deck dir with index.html and no new-slide request → run only the 4 validation gates (static + tokens + HTTP smoke + Playwright visual); (3) standalone — no spec → recommend deck-plan, or run a 4-question mini-scoping. Triggers on 'build the deck', 'generate slides', 'make a workshop/lecture/talk deck', 'deck audit', 'validate my deck', 'add a slide'. Every deck must pass all 4 gates before it is declared done.

Use when the user wants to PLAN a presentation deck from a thesis, outline, article, or script — before any HTML is generated. Turns source material of any kind into a reviewed slide plan (.planning/deck-spec.md): deck type (workshop / lecture / talk), scoping dialog (source, identity, sections, archetypes, demos, presenter scale, output dir, language), then one plan line per slide (archetype · title · key message · source span). Triggers on 'plan a deck', 'plan my slides', 'slide plan', 'outline a presentation', 'deck spec', 'prepare a workshop/lecture/talk from this doc'. Hands off to deck-build, which generates the HTML.