dotfiles

This repo holds CJ's home folder config and CJ's skills and mods for coding agents.

• The home folder config is a home-manager config. flake.nix and home/ put the Claude Code, Codex, zsh, nvim and tmux config in ~.
• The skills are in plugins/, in seven plugins. The mods are in mods/. marketplace.json lists both for Claude Code.

A skill is a method that an agent reads when a task needs it. Each skill must work in each agent tool that CJ uses. Success in SCOPE.md lists these tools. A mod is a set of hooks for Claude Code only.

• Home: set up a new machine, change a home file, and sync settings.json.
• Install: install the skills in Claude Code or in another agent tool.
• Skills: each skill, its plugin, and what it does.
• Mods: each mod and what it does.
• Models: which model does what.
• Scope: what dotfiles is, its success criteria, and the ideas it rejects, each with its reason.
• painting-craft: before and after: two pictures from the original skill and from the current skill.

Install

The skills ship in seven plugins. Install only the plugins that you need.

Plugin	What it is for	Skills
design	Sign off UI work and motion. Check it against the design, add missing microinteractions, and make launch videos.	ui-polish, microinteraction, launch-video
engineering	Prove the work in the real app with playbooks, design-first builds, unattended loops, bug hunts, code history, review and PRs.	playbooks, break-it, feature-files, interrogate, commit, create-pr, architect, implement, drive, bug-hunt, blast-radius, self-verify, formal-verify, no-comments, cleanup, how, why, teach
planning	Turn an idea into tickets. Find and test ideas, write the spec, cut thin slices, and triage them in any tracker.	vision, shape, tickets, grill, scout, triage
knowledge	Keep what the team learns: a decision log, research pages, lessons from past sessions, and a recap of recent work.	project-knowledge, hone, recall
visual	Paint scenes in code to a gallery standard.	painting-craft

The engineering principles are prompts you paste, not a plugin: see Prompts.

Prompts

Engineering principles and two rewrites, as prompts you paste into a session. Each link opens the prompt, ready to copy.

Prompt	What it finds
Model the Domain	All implicit state machines, booleans kept in sync, and branch chains that one table or union would replace.
Foundational Thinking	Logic written before its data shapes, and one capability spread as special cases across callers.
Type System Discipline	Interchangeable primitives, hand-copied schema types, casts on external data and non-exhaustive variants.
Boundary Discipline	Checks inside the system that belong at its boundary, and logic that cannot run without the framework.
Make Operations Idempotent	Steps that break when they run twice or after a crash at any point.
Separate Before Serializing Shared State	Two writers on one file, key or branch, to split before you add a lock.
Laziness Protocol	One decision made in two places, and parameters passed through untouched.
Subtract Before You Add	Dead code, stubs and guards that no spec or use needs.
Minimize Reader Load	Wrappers with one caller, and state wider than it needs to be.
Redesign From First Principles	A new flag beside an old path, and the design you would build from zero.
Outcome-Oriented Execution	Shims that exist only to keep a middle step green.
Exhaust the Design Space	The best of 2 or 3 small prototypes, for a decision with no precedent.
Experience First	Options added because they were easy, and reports that list files instead of effects.
Build the Lever	Hand edits that a script could do and prove.
Fix Root Causes	Guards for states that must never exist, and sibling copies of the same bug.
Attack the Premise	Fixes that share one untested premise, tested before the next fix.
Prove It Works	"Done" that rests on a proxy: a cache, an old build or a self-report.
Test Behavior, Not Implementation	Tests that pass when behavior breaks, or fail on a refactor.
Explain the Number	Numbers with no named limiter: the core, lock, disk or network that capped them.
Sequence Verifiable Units	Checks against a stale base, and commit orders that prove nothing.
Find Implicit Invariants	Every invariant the code assumes but never enforces, with the path that breaks it.
Follow the Dependencies	Code bolted on against the dependency direction, and the simpler shape the dependencies imply.
Re-pitch	Rewrite: your last message again, with the missing context first and one diagram.
Unslop	Rewrite: the same text without the tells of AI-written prose.

Claude Code

1. Add the marketplace.
2. Install each plugin that you need, and each mod that you need.

claude plugin marketplace add cpeaustriajc/dotfiles

claude plugin install engineering@dotfiles

To edit a skill or a mod, add your clone as the marketplace in place of the repo: claude plugin marketplace add ~/Projects/dotfiles.

If you installed plugins from the cj-stack marketplace before, follow Migrate from the cj-stack and cj-lab plugins.

Other agent tools

To link all the skills into ~/.agents/skills, run this script from the clone. Codex reads this folder.

scripts/link-skills.sh

To link them into another folder, give the folder as the first argument. Never give ~/.claude/skills, because the plugins already list the skills there. The mods do not work outside Claude Code.

Skills

The agent starts a skill when your request matches the skill's description. A typed skill starts only when you call it by name.

Skill	Plugin	What it does
ui-polish	design	Reviews a UI and its motion against the design and a list of common mistakes. It gives a Before/After/Why table.
microinteraction	design	Typed, with an area of a web UI. Finds the places that should animate, and plays each proposal before you pick one. It builds nothing.
launch-video	design	Makes a narrated launch video from a live site or a brief, with a voiceover, music, thumbnails, captions and post copy.
playbooks	engineering	Gives the playbook for a bug, refactor, performance problem, feature, prototype or design. Each playbook has its own proof, such as a reproduced bug.
break-it	engineering	Drives the app as a careless, impatient or confused user with worst-case data. Reports ranked bugs with screenshots, video and repro steps.
feature-files	engineering	Keeps one short file for each feature that says how to reach, drive and check it. An E2E check reads only the file that it needs.
interrogate	engineering	Reviews a diff with fresh reviewers, each on a different slice. Sorts the findings into act on, consider, noted and dismissed.
commit	engineering	Typed. Commits the changes in small slices in the repo's style, then pushes. With local, it does not push.
create-pr	engineering	Commits, runs the fast checks, pushes, and opens a PR that links the issue and the evidence.
architect	engineering	Typed, with a task. Sketches the types, signatures and module structure before the code, then stays in the loop while the build fills them in.
implement	engineering	Typed, with a ticket or a spec. Builds each ready ticket without supervision, with the feature playbook, a review and a PR.
drive	engineering	Writes the exit check first, then makes one change for each pass and keeps or reverts it. It stops when progress stops.
bug-hunt	engineering	Hunts bugs across a codebase in rounds, and fixes each bug test-first. It stops when a round finds no bug.
blast-radius	engineering	Typed, with a change. Finds what the change can break outside its diff, and runs code to prove the fact that makes it safe.
self-verify	engineering	Sets up and audits the repo's verify skill, so that agents prove "done" with a verdict for each PR.
formal-verify	engineering	Model-checks a race, retry, lease or state machine that tests miss. Writes or maintains a project verify skill for the model.
no-comments	engineering	Typed, with a folder. Removes stale comments and suppressions in separate commits, with the same test results.
cleanup	engineering	Removes what a session left, such as dev servers, stale branches and the session itself, when it is safe. It does not tidy code.
how	engineering	Typed, with a question. Explains how a part of the code works, and where a new piece should go.
why	engineering	Explains why code is like it is, where a number came from, or if a guard can go. Labels the evidence from git, PRs and docs.
teach	engineering	Typed, with a subject. Runs how and why, and gives one plain explanation of what they find.
vision	planning	Asks you about a product idea, first whether it is worth building. Then writes the plan for the product. It does not find ideas.
shape	planning	Writes the spec, milestones and status updates for one project in any tracker, such as Linear, Jira or GitHub.
tickets	planning	Cuts a spec into thin slices that each cite their requirements, or writes one bug or chore.
grill	planning	Sizes a change, then asks you rounds of questions with a recommended answer each, until no decision is open.
scout	planning	Finds an idea worth building, or checks a niche, when apps are cheap to copy. It gives the best idea to vision.
triage	planning	Sets one state on an issue, for "what needs my attention" or "can an agent take this". Writes an agent brief.
project-knowledge	knowledge	Keeps decision and research pages where the team writes, such as a GitHub wiki, Notion, Obsidian or Confluence.
hone	knowledge	Finds your repeated corrections in the transcripts on this machine, and proposes where each lesson goes.
recall	knowledge	Gives a brief of recent work from transcripts, git and PRs.
painting-craft	visual	Draws and paints in code to a gallery standard, with a screenshot review loop. It is not for UI icons, charts or diagrams.

A skill holds no tool details and no project facts. The tool details go in the skill's references/<tool>.md adapters. A project's own facts stay in that project.

Mods

The mods are Claude Code plugins. To install a mod, run claude plugin install <mod>@dotfiles.

Mod	What it does
hone-nudge	Suggests /hone <skill> after you correct Claude during a dotfiles skill.
memory-lint	Denies an auto-memory write that holds task state, short-lived detail, PR or commit references, file:line pointers, code, or too much text. A prune always passes.
test-guard	Denies an Edit or Write that changes or removes a test line at HEAD. Additions pass. /test-guard allow <path> lets one file change.

painting-craft: before and after

Each prompt ran once in a fresh session. The left picture is from the original skill. The right picture is from the current painting-craft. Nobody touched up a picture by hand.

"Paint a 1600x1000 SVG of a knight asleep against an oak tree at dusk, in a Romantic oil-painting look."

At 2× zoom on the knight, the current skill paints a 3D figure that the low sun lights. The figure has separate plates, rows of mail and a visor. The original skill painted a mannequin of tubes.

"Draw a night city street as a 1600x1000 SVG: a car passes behind a row of trees on the near verge. Flat vector style, but it must not look cheap."

At 2× zoom on a tree, the current skill builds each crown from clumps on a branch skeleton, in three values with broken edges. The original skill piled up round blobs.

These changes to painting-craft made the difference:

• Build recipes for the parts that fail up close, in references/recipes.md.
• A study of each hero element against fetched public-domain references before the composition, with scripts/refs.py and scripts/compare.py.
• The bundled 3D figure renderer.
• A paint pass that unifies the painted styles, with scripts/paintpass.py.
• Delivery at twice the display size.