codacy-specs
A Claude Code plugin by Codacy that audits any specification for AI-agent readiness and rewrites it to be clear, testable, and unambiguous.
Vague specs are the leading cause of AI coding failures. If a ticket clearly states what to build, defines inputs/outputs, specifies error handling, and provides verifiable acceptance criteria, AI agents produce better code with fewer wrong assumptions.
Features
- Spec audit: Score any spec on a 0–100 rubric across problem statement, acceptance criteria, error handling, edge cases, testability, and type-specific dimensions
- Spec type detection: Automatically identifies API endpoint, UI component, backend feature, bug fix, data migration, or generic specs
- Guided clarification: Asks one focused question at a time to fill critical gaps — never fabricates context
- Spec rewrite: Produces a fully structured, AI-agent-ready spec using proven templates
- Multi-source: Works with Jira issues, Linear issues, local files, or inline pasted content
- Write-back: Updates the original Jira or Linear issue directly after user confirmation
- Project-aware: Reads your
CLAUDE.md to understand your team's conventions and terminology before auditing
Installation
1. Install the plugin
Add this plugin to your Claude Code project:
# From your project root, or globally
claude plugin marketplace add codacy/codacy-specs
claude plugin install codacy-specs
Or clone and install locally:
git clone https://github.com/codacy/codacy-specs
claude plugin marketplace add ./codacy-specs
claude plugin install codacy-specs
2. (Optional) Connect Jira and/or Linear
This plugin does not bundle its own MCP configuration. If you want to audit and update issues directly in your tracker, install the dedicated plugin or MCP server for that tool:
Once a tool's MCP is active, spec-improve will automatically use it to fetch and update issues.
No issue tracker connected? The skill works without any of them. Paste any spec directly into the chat, or point it at a local file — it will audit and rewrite without needing any external connection.
3. (Recommended) Add project context to CLAUDE.md
The skill reads your project's CLAUDE.md before every audit. This is the single most impactful thing you can do to improve audit quality: the skill will not flag terms or patterns that are already defined there.
Two things worth adding to your CLAUDE.md:
Terminology — internal acronyms, service names, and domain concepts your team uses:
## Terminology
- **SRM** — Security Risk Management service. Core internal microservice for vulnerability scanning.
- **org** — An organization account in our multi-tenant model. Maps to the `organizations` table.
- **PDQ** — Priority-Driven Queue. Internal async job scheduling system.
API and engineering conventions — defaults and standards your team follows that don't need to be re-stated in every ticket:
## API Conventions
- All endpoints return `application/json` unless stated otherwise.
- Pagination uses `?page=` and `?pageSize=` query params. Default page size is 20, max is 100.
- Authentication is via Bearer token (JWT). All endpoints require auth unless explicitly marked public.
- Error responses follow the shape `{ "error": "ERROR_CODE", "message": "..." }`.
The skill uses this context during auditing: if a convention in CLAUDE.md covers a gap in the spec, the gap is scored as covered rather than missing.
Why CLAUDE.md and not a separate file? Because knowledge in CLAUDE.md benefits all Claude interactions in your project, not just spec audits. One source of truth.
Usage
The spec-improve skill activates automatically when you use natural language like:
audit this spec
improve this Jira ticket PROJ-123
review this Linear issue ENG-42
improve GitHub issue #42
audit github.com/my-org/my-repo/issues/99
rewrite this story to have better acceptance criteria
check if this spec is ready for an AI agent
make this ticket clearer
improve the spec in docs/spec.md
It also activates as a pre-work guardrail when you (or an agent) are about to start implementing a ticket:
start working on PROJ-123
implement this ticket
pick up the next item
In this mode it runs a quick readiness check and offers to either review and improve the spec, or continue straight to implementation.
Example: Audit a Jira issue
You: improve this Jira ticket PROJ-123
codacy
devstefancho
Dev-GOM
dapi
rhuss
jeanluciano
giuseppe-trisciuoglio