pivoshenko.ai: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

pivoshenko's AI agent workspace. Two things live here:

1. Source of truth for agent config — locally authored skills (skills/), MCP definitions (mcps/), and instruction rules (instructions/), plus kasetto.yaml, which lists both the local assets and the external upstream repos to pull from. Kasetto (kst sync) distributes all of it into ~/.claude/. Instructions land in ~/.claude/CLAUDE.md as managed blocks, so the files in instructions/ are the global agent rules.
2. site/ — a Next.js catalog viewer at ai.pivoshenko.dev that reads the files above off the parent filesystem at build time.

Most edits here are Markdown/YAML/JSON config, not code.

Commands

All recipes run from the repo root and delegate into site/ (just + pnpm; Node >= 24, pnpm 10.30.3 pinned via packageManager).

just install   # pnpm -C site install
just dev       # next dev --turbopack
just check     # biome check . --write, then next build (run before committing)
just lint      # biome lint . (read-only, what CI runs)
just format    # biome format . --write
just build     # next build
just start     # build + next start
just audit     # pnpm audit
just update    # pnpm update
just test      # no-op while the `.no-tests` sentinel exists

There is no test suite. just test succeeds only because the empty .no-tests file at the repo root exists; deleting it makes the recipe fail hard (and breaks CI) until a real test command replaces it.

CI (.github/workflows/ci.yaml, push to main + PRs, ubuntu-24.04-arm, Node 24) runs just install && just lint && just audit && just test && just build. CI uses lint (non-writing) while local just check writes fixes — run just check locally so CI's lint stays clean.

Asset layout and the sync contract

• kasetto.yaml decides what actually syncs. The local source (github.com/pivoshenko/pivoshenko.ai) uses "*" for instructions and skills, so new files in those dirs sync automatically. mcps are enumerated by name (currently github, vercel, cloudflare, logfire), so adding mcps/foo.json also requires adding foo to the mcps: list. mcps/motherduck.json and mcps/supabase.json exist on disk but are not listed — they show on the site (which globs mcps/*.json) and do not sync.
• skills/<slug>/SKILL.md is required; references/, scripts/, assets/ are optional siblings loaded on demand (see skills/pivoshenko-brand for the full shape).
• instructions/<slug>.md — one rule per file, frontmatter + rule body.
• mcps/<name>.json — shape is { "mcpServers": { "<name>": { ... } } }. Secrets are Kasetto placeholders (${kst_github_token}), never literals.
• archive/ mirrors the live layout (archive/skills/, archive/instructions/, archive/scripts/). Kasetto only pulls from the top-level dirs, so retire by moving here, not deleting — the site still renders archived skills/instructions in a dimmed section.