jonathanung-plugins

Finesse

A Claude Code plugin that turns vague task descriptions into validated, ready-to-run prompts for iterative autonomous development — the kind that converge instead of thrashing. Describe what you want in plain English; Finesse plans it, validates it with parallel agents, and executes it.

How does iterative execution work? Finesse ships its own execution layer (based on the ralph-loop plugin) that repeatedly invokes Claude to work on a task across multiple iterations until a completion condition is met. Each iteration is stateless — the agent starts fresh with only the prompt and the current state of the codebase. This makes prompt quality critical: a vague requirement becomes an infinite loop, a missing guardrail lets the agent delete your tests, and an ambiguous "done" condition means it either exits too early or never stops. Good prompts need 10 specific attributes that Finesse encodes automatically.

How It Works

/finesse:finesse Build a REST API for managing todos with authentication

Finesse detects your task type, explores your codebase, asks you clarifying questions, designs implementation approaches, constructs the prompt, validates it with specialized agents, and presents the result for your approval — then executes it.

You → /finesse:finesse "vague idea"
       ↓
  Task Classification (feature / bugfix / refactor / testing / performance / research)
       ↓
  Codebase Exploration (2-3 agents in parallel)
       ↓
  Scope Analysis & Decomposition (split large tasks into parallel sub-workflows?)
       ↓
  Type-Specific Workflow  ←  you answer clarifying questions
       ↓
  Prompt Construction (cold start, ordered phases, verification commands, guardrails)
       ↓
  Parallel Validation (6 agents in parallel)
       ↓
  Refinement (auto-fix or ask you)
       ↓
  Presentation  ←  you approve or reject
       ↓
  On Accept → finesse-plans/ output + execute or copy command(s)

Installation

# Add the marketplace
/plugin marketplace add jonathanung/finesse

# Install the plugin
/plugin install finesse @ jonathanung-finesse

Finesse ships its own execution layer — no additional plugins are required.

Commands

/finesse:finesse <TASK> [--max-refinements N]

Plan and validate a prompt for any development task.

• TASK — What you want to do. Can be vague — Finesse will clarify.
• --max-refinements N — Max planning refinement cycles (default: 5). This is Finesse's internal planning budget, not the execution iteration count. Finesse determines the iteration count automatically based on task scope.

# Features
/finesse:finesse Build a REST API for managing todos with auth
/finesse:finesse Add a dark mode toggle to the settings page

# Bug fixes
/finesse:finesse Fix the token refresh bug in auth.ts
/finesse:finesse The search endpoint returns duplicates when filters overlap

# Refactoring
/finesse:finesse Refactor the database layer to use repository pattern
/finesse:finesse Clean up the payment service — it's 800 lines

# Testing
/finesse:finesse Add integration tests for the payments module
/finesse:finesse Write unit tests for the email validation logic

# Performance
/finesse:finesse Optimize the search endpoint — it's taking 3+ seconds
/finesse:finesse The dashboard page takes 5s to load

# Research
/finesse:finesse Research whether we should use Redis or Memcached for caching
/finesse:finesse Investigate the trade-offs between REST and GraphQL for our API
/finesse:finesse Evaluate feasibility of migrating from Postgres to CockroachDB

Example Output

For /finesse:finesse Fix the token refresh bug in auth.ts, Finesse produces something like:

/finesse:finesse-execute --prompt-file finesse-plans/fix-token-refresh-auth.md --completion-promise-file finesse-plans/fix-token-refresh-auth-promise.txt --max-iterations 8

Finesse saves three files:

• finesse-plans/fix-token-refresh-auth.md — the prompt only: cold start paragraph, ordered fix-then-test phases, verification commands, and guardrails
• finesse-plans/fix-token-refresh-auth-promise.txt — the completion promise text
• finesse-plans/fix-token-refresh-auth-plan.md — metadata: task type, codebase context, chosen approach with rationale, iteration reasoning

/finesse:finesse-execute [--prompt-file PATH] [--completion-promise-file PATH] [--max-iterations N] [PROMPT...]

Execute a plan using Finesse's built-in execution layer. Can auto-detect plans from finesse-plans/, take explicit file arguments, or accept an inline prompt.

/finesse:finesse-mini <TASK>

Lightweight single-pass alternative to /finesse for micro-tasks (fix a typo, add a missing import, rename a variable across a few files). Skips the full multi-phase workflow — explores 1-5 files, constructs a prompt, validates with 3 agents, and presents.