codacy-specs

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:

• Jira: Install the Atlassian Claude Code plugin
• Linear: Install the Linear Claude Code plugin
• GitHub Issues: Add the GitHub MCP server

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