Clank

Clank is a Claude Code plugin that turns a rough idea into shipped, reviewed, spec-compliant code through a fixed pipeline of skills: brainstorm and spec it (/define), implement it test-first (/implement), audit it for code quality (/review), verify it against the spec (/validate), and keep the project's CLAUDE.md clean (/gc). Each stage hands off to the next only once its own gate passes — a written spec, passing tests, a clean audit — so an agent can't skip ahead or claim done without evidence. Run the whole chain unsupervised with /yolo, or drive it stage by stage and approve each step yourself.

Install

/plugin marketplace add niconisoria/clank
/plugin install clank@clank

Skills

Skill	Role
/init	Bootstraps CLAUDE.md — tech stack, folder purposes, and iron-law rules only. Run once per project, before /define.
/define	Entry point. Guides idea through brainstorm → spec → design, then hands off to /implement.
/implement	TDD loop. Reads spec, researches prior art, writes failing tests, implements until they pass. Hands off to /review.
/review	Deep code-quality and design-pattern audit (SOLID, coupling, abstraction level, duplication, security, dead code). Hands off to /validate.
/validate	Spec-compliance check (ACs, intent, edge cases, architecture, UI, integration), then wraps up.
/gc	Maintenance. Prunes stale, duplicate, derivable, out-of-scope, and unverifiable entries from CLAUDE.md and docs/ files.
/yolo	Runs define→implement→review→validate back to back, zero user input. Auto-decides every question/approval, logs each decision to the spec's ## Autopilot Log. For unsupervised/background runs.

Workflow

flowchart TD
    A([User + idea]) --> B[define: ask up to 3 questions]
    B --> C[define: write Brainstorm section]
    C --> D{approve?}
    D -- changes --> C
    D -- yes --> E[define: write Story + ACs]
    E --> F{approve?}
    F -- changes --> E
    F -- yes --> G[define: write Design + Modules]
    G --> H{approve?}
    H -- changes --> G
    H -- yes --> I([Run /implement spec-path])
    I --> J[Detect framework]
    J --> K{detected?}
    K -- no --> L([ask user])
    K -- yes --> M[Research prior art in specs + codebase]
    M --> N[Write failing tests]
    N --> O[Write implementation]
    O --> P{tests pass?}
    P -- no, up to 5 --> O
    P -- yes --> Q([Run /review spec-path])
    Q --> Q2[Audit: SOLID, coupling, abstraction, duplication, security, dead code]
    Q2 --> R{issues?}
    R -- fix + retry, up to 3 --> Q2
    R -- clean --> S([Run /validate spec-path])
    S --> S2[Check ACs, intent, edge cases, architecture, UI, integration]
    S2 --> S3{gaps?}
    S3 -- fix + retry, up to 3 --> S2
    S3 -- clean --> T[Append file refs + Summary to spec]
    T --> U[Update docs/MEMORY.md]
    U --> V[Mark spec: implemented]
    V --> W([Done])

Loading

Evals

Model-graded eval suite for the skills. For each task in evals/eval_dataset.json: generate a solution under the target skill's SKILL.md, then grade it against that task's solution_criteria with a second Claude call acting as judge.

uv sync
uv run evals/evaluate.py                  # all skills
uv run evals/evaluate.py --skill define   # one skill

Reads ANTHROPIC_API_KEY from evals/.env (see .env.example) or the environment. Prints a pass/fail summary per skill and writes evals/report.json.

Hooks

Hook	Trigger	Blocks
file-guard.sh	Write / Edit	.env, key files, bin/ writes, out-of-root paths, secret patterns in content
bash-guard.sh	Bash	rm -rf, force push, pipe-to-shell, shell reads of key files
commit-guard.sh	Bash	non-Conventional-Commits commit messages
post-edit-tests.sh	Write / Edit (post)	nothing — runs the test suite after each source-file change

Structure

hooks/
  hooks.json        — plugin hook registration (loaded when installed as a plugin)
  *.sh              — guard/test scripts, referenced via ${CLAUDE_PLUGIN_ROOT}
evals/
  eval_dataset.json — task suite: skill, task, expected format, solution_criteria
  evaluate.py       — runs the model-graded eval, prints summary, writes report.json
docs/
  specs/            — feature specs (status-tracked, workflow-owned)
  MEMORY.md         — decision rationales: why X over Y, never file paths or patterns
  architecture.md   — system-wide structural decisions (hand-maintained, optional)
  design-system.md  — colors, tokens, UI rules (hand-maintained, optional)

CLAUDE.md — tech stack, folder purposes, and iron-law rules only. Everything else goes in docs/.