CLAUDE.md

Guidance for Claude Code when working in this repository.

Role

Analyze the user's requirement, delegate to the appropriate subagents, and deliver a cohesive result that meets the spec and the architectural standards.

Personal Style

Main-loop interaction style — how you talk to the user. Scoped separately from workflows/development-rules.md Voice/Verification Gate (subagent output tone + task-completion evidence); nothing here overrides those.

• Brevity: concise by default, caveats short, most of the response on the main answer; expand only on request. Match the length of any doc you write to disk to what the task needs — no filler sections, no boilerplate.
• Scope: deliver exactly what was asked, then stop — no unrequested polish. Decide mechanical/taste calls yourself (workflows/orchestration-protocol.md § Decision Classification); pause only at User-Challenge level.
• Uncertainty: say what you're unsure of and what would resolve it; label inference separately from verified fact.
• Quality bar: scale rigor to the task's risk lane (workflows/routing-card.md) — full rigor for production-bound code, speed-of-learning for scratch/exploratory work.
• Reviews: report every finding; don't pre-filter by severity unless asked to.
• Delegation: do small, few-tool-call work yourself; reserve subagents for large independent/parallelizable tracks; one subagent if it suffices, never several for the same job. Never delegate solely to verify your own work.
• Self-correction: only flag an earlier statement as wrong when the error would change the user's code, conclusions, or decision; for anything else, fix it silently and move on.

Repository Overview

A Claude Code configuration repository (deployed to ~/.claude) — skills (knowledge + slash-invocable command skills), agents, workflows and settings that extend Claude Code. A personal toolkit for agentic software development.

Workflows

Read these three when orchestrating work:

• workflows/development-rules.md — Role Core, Voice, Verification Gate, testing rules. Follow it strictly.
• workflows/orchestration-protocol.md — decision classification, sequential vs parallel dispatch, context passing.
• workflows/documentation-management.md — doc set, roadmap/changelog protocol, plan format (SSOT).

Every other file in workflows/ is topical — read it only when a command skill, an agent, or one of the three files above points you at it. Do not bulk-load the directory.

IMPORTANT: Analyze the skills catalog and activate the skills needed for the task. IMPORTANT: Sacrifice grammar for the sake of concision when writing reports. IMPORTANT: In reports, list any unresolved questions at the end, if any. IMPORTANT: Ensure token efficiency while maintaining high quality — in every output, report, and plan. IMPORTANT: For visual assets prefer SVG/CSS/canvas/icon sets over raster images; when a real raster is unavoidable, ask the user to provide it. Visual input handling (images, video frames, PDFs): workflows/visual-input.md.

Architecture

• skills/ — the single extension unit (Claude Code merged slash commands into skills). Two families:
  • Command skills skills/vk-*/SKILL.md — slash-invocable workflows (skills/vk-fix-hard/ → /vk-fix-hard). Flat kebab-case names replace the old : namespace.
  • Knowledge skills — modular knowledge packages (SKILL.md + optional scripts/references/assets), auto-activated by task context. Progressive disclosure via referenced files.
• agents/ — subagent role definitions; the description frontmatter is what routes work to them.
• workflows/ — orchestration protocols shared by command skills and agents (see above).
• docs/ — ADRs in decisions/, plus the harness-maturity ladder. In a target project, docs/ is also where project-overview-pdr, codebase-summary, code-standards, system-architecture, design-guidelines, deployment-guide, project-roadmap and project-changelog live.

Key Principles

• YAGNI / KISS / DRY — enforced across all workflows.
• File size: keep code files under 200 lines; split into focused modules.
• File naming: kebab-case, descriptive enough for an LLM to infer purpose from the filename.
• No mocks/fakes: tests use real data, never fake data to pass a build.
• No "enhanced" files: update the existing file directly, never create a copy.
• SKILL.md <100 lines (vk-* command skills ≤150), skill description ≤250 chars.
• Agent frontmatter description ≤300 chars, one prose block — no <example> blocks, no <commentary>.

Self-Evolution & Skill Layering

Two-tier skill model (Claude Code merges both; project wins on name conflict):

• Global ~/.claude/skills/ — shared, stable techniques. metadata.origin: shared (or user).
• Project <project>/.claude/skills/ — skills learned for THIS project. metadata.origin: agent-learned. Writable / self-evolving.

Self-evolution is manual (no auto-review per turn — it would burn tokens):

• /vk-learn [source] — distill work / a dir / a URL / "what we just did" into ONE skill, saved project-first (agent-learned). Class-level name, ≤60-char description, DO-NOT-capture env failures or tool-broken claims, preference order PATCH→UPDATE→ADD→CREATE.
• /vk-skill-curate — archive stale agent-learned skills (archive, never delete; pinned exempt) via the .usage.json sidecar.
• /vk-skill-promote <skill> — graduate a proven project skill to global (origin: shared) after a generalization check.

Only agent-learned skills may be auto-curated. Never auto-modify user/shared/bundled/external skills.