Klerith/fernando-skills

What it solves

When you give an LLM like Claude Code a broad request such as "build me an Arkanoid game," it tends to improvise silently—making dozens of design decisions (class vs. function, global vs. local state, naming, etc.) without your input. Each of those decisions becomes costly to reverse later. The problem is worse with LLMs because they generate code so quickly that decisions become invisible, every conversation starts fresh without memory of prior choices, and you waste context pasting the same context manually. This project solves all three by making the spec the central artifact: it forces explicit decisions, persists them across sessions, and loads once as a stable reference.

How it works

This project provides two Claude Code skills that work as a pair. The /spec skill walks you through designing a feature spec. It reads your project's memory file (CLAUDE.md, AGENTS.md, or README.md) and any existing specs, then asks clarifying questions in blocks of 3–5 until the feature is clear. It builds the spec section by section, each part confirmed with you before moving on, and finally saves it as specs/NN-slug.md with status Draft.

You then re-read the spec outside the chat (in your editor) and manually change the status to Approved—a deliberate human act, since Claude cannot approve its own work. Only after you approve does /spec-impl become usable.

The /spec-impl skill locates the spec, validates its status is Approved, creates a git branch (e.g., spec-03-levels-and-highscores) unless configured otherwise, and then implements the spec step by step according to the ordered plan. After each step it pauses so you can review the diff. If anything needs to change mid-implementation, you go back to plan mode and update the spec—never improvise directly on code.

The spec itself follows a six-part structure described in the README: a one-sentence goal, explicit in-scope and out-of-scope items, a data model with concrete names and paths, an ordered implementation plan where each step leaves the system in a working state, verifiable acceptance criteria (boolean checklist items like "Pressing Esc pauses the game and shows the menu"), and a record of decisions made and discarded with reasons.

Who it's for

This is for developers using Claude Code (or other coding agents like Cursor, Codex, or Antigravity via the included installer) who want to avoid the chaos of unplanned LLM code generation. It's ideal when a task touches more than two files, involves decisions that are expensive to revert (schemas, formats, APIs), takes longer than one session, or produces a contract reused by other artifacts. It's not meant for trivial bug fixes, mechanical refactors, exploratory experiments, or one-off tasks where the whole thing fits in a single prompt.

Highlights

• Two paired skills: /spec (design) and /spec-impl (implementation).
• Specs are versioned in git and serve as a persistent design decision log.
• Human approval is required: you must manually change the spec status from Draft to Approved before implementation begins.
• Step-by-step implementation with pauses to review each diff—no more giant 400-line commits.
• Works beyond Claude Code: an installer script adapts the skills for Cursor, Codex, and Antigravity.
• The spec includes acceptance criteria that are verifiable booleans, not vague statements like "works well" or "good UX".
• A mental rule from the README: if you're tempted to open plan mode, you probably need it; if planning the feature bores you, you probably don't.