claude-damn — visual aid

1 · Identity — what the repo IS

Shape

Harness, not app

It reshapes how Claude Code behaves in your sessions — slash commands, permission rules, pre-tool hooks, cost logging. No service to deploy.

Foundation

Built on superpowers

The official superpowers plugin is the skill engine. claude-damn adds opinionated modifiers, review ladders, and harness guards on top.

A11y

Accessibility is load-bearing

Treated as a first-class design concern, not a post-hoc checklist. Skills prefer structured prompts over disruptive modals, avoid involuntary focus or tab shifts, and keep rejection semantics honest — a denied step is a question, not a conclusion.

Discipline

Disciplined git + isolation

Commits are deliberate and reviewable. .worktrees/, .checkpoints/, and .remember/ keep per-branch work and session state out of the main tree. Operator-specific commit style lives in rules/PERSONALIZATION.md.

2 · Skill composition — four modifiers stack

Every workflow name is a combination of four building blocks. Read the name left-to-right and each modifier adds one behavior to the pipeline.

Modifier vocabulary
Modifier	What it adds	Flag it flips
`super`	Brainstorm requirements before implementing	Planning phase ON
`duper`	Run inside an isolated git worktree	Workspace isolation ON
`cat`	Fan out to parallel subagents	Subagent execution ON
`tdd`	Red–green–refactor discipline	Test-first ON

Four families emerge from the combinations:

TDD — /tdd, /tdd-cat, /duper-tdd, /duper-tdd-cat
Brainstorm + TDD — /super, /super-cat, /super-duper, /super-duper-cat
Debug + Brainstorm + TDD — /super-fixer, /super-fixer-cat, /super-duper-fixer, /super-duper-fixer-cat, /super-duper-fixer-tdd-cat
Expert Review — /expert-review through /expert-super-duper-tdd-cat-review (10 variants)

Reading a name: /expert-super-duper-tdd-cat-review = expert review → brainstorm → worktree → TDD → parallel subagents. Top of the ladder; reserve for work that actually needs every modifier.

Beyond the combinators there are utility skills: /checkpoint-save, /checkpoint-resume, /check-yourself, /cost_, /cost-opt, /listen, /proceed, /sync, /tesseract, /jcvd, plus PR-feedback and fast-review skills.

3 · Repo map — where things live

claude-damn/
├── CLAUDE.md              opinionated project rules (model routing, style, testing)
├── README.md              setup + skill family overview
├── ROADMAP.md             transition plan → proper plugin package
├── CHANGELOG.md           what's landed on feat/transition-to-plugin
├── CHECKPOINT.md          current in-progress checkpoint (gitignored in worktrees)
├── settings.json          permissions, hooks, enabled plugins, model routing
├── policy-limits.json     policy budgets
├── pyproject.toml         uv-managed Python project
├── ruff.toml · ty.toml · .prettierrc     formatter configs
│
├── skills/                ~60 slash commands (the combinatoric library)
├── hooks/                 PreToolUse guards — block-inline-scripts.py is the big one
├── plugins/               marketplaces + cache for the 12 plugins used
├── src/                   extract_cost.py · statusline · sync-theme
├── scripts/               test-isolated.sh
├── tests/                 7 fidelity layers (structural → performance)
├── docs/superpowers/      design specs + implementation plans
│
├── cost-log/              per-session JSONL cost ledger
├── .remember/             session handoff notes (buffer/today/recent/archive)
├── .checkpoints/          save/resume work across sessions
├── .worktrees/            hidden, gitignored isolation branches
└── .serena/  .idea/  .github/  .venv/     tooling

Design specs and implementation plans: docs/superpowers/{specs,plans}/. Full combinatoric skill table: skills/README.md.

4 · Harness systems — runtime behavior

settings.json

Permission guards

Granular allow / ask / deny lists: blocks destructive gh ops, gates git commit, protects settings files. Deny-by-default on anything scary.

hooks/block-inline-scripts.py

Inline-script hook

PreToolUse Bash guard. Denies commands over 300 chars or with more than 3 statement separators (; && || | > < >> << newline). Forces multi-step work into separate calls or /tmp/ scripts.

src/extract_cost.py · /cost_

Cost tracking

Parses session JSONL for real usage fields and computes spend via Anthropic pricing. Logs go to cost-log/YYYY-MM-DD_HHmm_{session}.jsonl. /cost-opt compacts logs and surfaces routing suggestions.

.checkpoints/ · /checkpoint-{save,resume}

Checkpoint system

Save resumable context per branch, with automatic archive rotation. Paired with .remember/ (buffer/today/recent/archive/core) for session-to-session continuity.

Model routing: Sonnet for reads, config edits, ~/.claude work, short Q&A. Opus for multi-file refactors, subtle runtime bugs, new API/data-model design. Sustained Opus sessions get a /model opus suggestion; trivial tasks get a nudge back to Sonnet.

5 · Test fidelity ladder — cheapest to priciest

Default `uv run pytest` runs everything except `smoke` and `performance`.
Tier	Location	Checks	Cost signal
Structural	`tests/structural/`	Files, dirs, frontmatter	Cheap — existence only
Behavioral	`tests/behavioral/`	Skill body content, protocol rules	Cheap
Integration	`tests/integration/`	Cross-file references & consistency	Cheap
Harness	`tests/test_*.py`	settings.json, permissions, hooks, cost extraction	Cheap
Bats	`tests/*.bats`	Shell scripts (checkpoint-archive, sync-theme)	Moderate — needs `bats`
Smoke	`tests/smoke/`	Live skill invocation	Tokens · non-deterministic
Performance	`tests/performance/`	18-combo stress matrix	Expensive · non-deterministic

Parallelize with pytest-xdist for smoke/performance: uv run pytest -n auto. Skip -n on the default suite — it runs in ~0.5s and worker startup adds more overhead than it saves.