stack-evaluator

A Claude Code plugin that reviews a project's stack, not its code.

Code review tools tell you whether the code you wrote is good. They cannot tell you that the runtime went end-of-life last April, that there is no cache anywhere in a read-heavy API, that nothing backs up the database, or that you are running a message broker for forty events a day. Those are properties of the component list, and the component list is not in any file that a code reviewer reads.

This plugin works the component list. It records the stack into the repository with the date it was evaluated, so the next run is a comparison rather than another snapshot — and so decisions ("no cache, no measured load, decided 2026-05-02") stop being re-litigated every time.

What it does

Skill	Question
stack-inventory	What is this built from? Writes docs/stack/stack.json + stack.md, dated.
stack-currency	Is any of it out of date, past EOL, deprecated, or abandoned?
stack-gaps	What should be here and is not — caching, backups, queues, rate limiting, observability?
stack-fitness	Does the set still make sense — redundant, over-built, orphaned, or expired?
stack-proposal	What should change, in what order, and a brief an execution agent can act on.
stack-diff	Since the last run: what got fixed, what is chronic, what drifted?

Or run the lot: /stack-eval

Install

/plugin marketplace add danielrosehill/Claude-Code-Plugins
/plugin install stack-evaluator@danielrosehill

Use

/stack-eval                              # full evaluation
/stack-eval --quick                      # inventory + gaps + short proposal
/stack-eval --appetite minimal           # only propose what is worth doing now

Or invoke a skill directly — "is my stack up to date", "am I missing caching", "does this stack still make sense", "what changed since the last review".

What it writes

docs/stack/
├── stack.json                        # the record — components, decisions, findings, run history
├── stack.md                          # generated human view
├── proposal-<date>.md                # target state + sequenced work items
├── execution-brief-<date>.md         # self-contained handoff for an implementing agent
└── reports/
    ├── <date>-currency.md
    ├── <date>-gaps.md
    ├── <date>-fitness.md
    └── <date>-diff.md

stack.json is the file that matters. It carries three things forward between runs:

• Settled decisions — a slot marked intentionally-absent with a reason and a date is not raised again.
• Finding age — first_seen is never reset, so something open across four runs reads as chronic instead of new.
• Rejections — a finding you decided against stays rejected.

Without those, a second evaluation just repeats the first one and the plugin becomes noise.

Design decisions

Slots, not freehand. The stack is described against a fixed list of ~50 component slots (references/component-taxonomy.md). A freehand description only ever lists what exists; a slot list also shows what does not.

Archetype-relative. A static site needs no queue. An authenticated API with no rate limiting is a real finding. Expectations come from the project's archetype (references/archetype-checklists.md), not from a universal reference architecture.

Caching is asked about explicitly, at all five layers — edge, HTTP, application, data access, client — because it is the slot most often silently absent. It is only reported as a gap where there is evidence of something worth caching; adding a cache to an unloaded system is itself an anti-pattern.

Being behind is not automatically a defect. A supported component two minors back gets a passing grade and a one-line mention. Findings are for EOL, near-EOL, deprecated-with-successor, abandoned, unpatched, or actually blocking something.

Right-sized recommendations. The lightest fix that closes the gap, with the heavier option noted as the upgrade path and the signal that would justify it. Postgres SKIP LOCKED before Kafka; a TTL map before Redis; a compose file before Kubernetes.

Evaluation and execution stay separate. Nothing in this plugin changes a stack. It ends at a proposal and an execution brief that authorises exactly what it lists — so there is a decision point, and so an implementing agent does not read "stack review" as licence to modernize everything it sees.

Scope

Not a code reviewer, not a security scanner, not a dependency-vulnerability tool, and not a performance profiler. It reads manifests, lockfiles, configs, compose files, CI definitions and infrastructure declarations — the places where a stack declares itself — and asks the user about the parts that live outside the repository.

Licence

MIT