implement-idea

name	implement-idea
description	Turns a raw idea or feature request (no GitHub issue) into a confirmed mini-spec by asking follow-up questions about scope, desired outcome, and success criteria, then implements it with the same rigor as /implement-issue: reads AGENTS.md/area context and applicable stack/conventions skills, runs a full-context investigation, invokes the grill skill when registered, presents exactly three options and stops for the user's choice before coding, updates the branch against origin's default branch, implements the chosen option, searches project context for DEFINITION_OF_READY.md before implementation, runs verification (UI/UX checks plus the project's full check gate), reviews against the spec's success criteria and project-context DEFINITION_OF_DONE.md before handoff, runs a /review code review, and always hands off via /create-pr. Use when the user runs /implement-idea or wants to build something that is not an existing issue.
license	Unlicense OR MIT
compatibility	Requires git and the GitHub CLI (gh) for the /create-pr handoff, plus network access; verification examples assume a Bun toolchain.

Implement idea

Instructions

Turn a raw idea into a confirmed mini-spec, then implement it in the current repository. This is /implement-issue without a GitHub issue — the idea-formulation phase (step 2) produces the spec that an issue would otherwise provide.

Non-negotiable gates (do not skip, do not rationalize)

These five gates are mandatory. Most failures of this skill come from skipping one of them under time pressure or because the idea "looks simple." Being an implementation command is not a license to skip any gate.

1. GATE A — Formulate and confirm the idea before anything else. You must complete the questioning in step 2 (scope, outcome, success criteria — shaped like a well-structured issue, borrowing /create-issue's components) and get the user's explicit confirmation of the written mini-spec before investigating, grilling, or planning. Do not start designing from a vague one-liner.
2. GATE B — Grill before planning. When a grill skill is registered, you must invoke it (step 5) before presenting options. Do not proceed to options without it.
3. GATE C — Full-context investigation before concluding. You must complete the investigation in step 4 (enumerate the project's real commands, trace the relevant code paths) before forming any conclusion. A conclusion drawn from a single file or a guessed command is invalid.
4. GATE D — Wait for the user's choice. After presenting options (step 7) you must stop and wait for the user to pick one. Do not continue to implementation on your own.
5. GATE E — Code review, then hand off (do not stop early). Whenever there is a code or test change to ship, you must run a code review via /review (step 15) and then invoke /create-pr (step 16). Finishing by only summarizing the change in chat, without running the review and opening the PR, is a failure of this skill.

Forbidden rationalizations — if you catch yourself writing any of these, you are violating the skill, stop and follow the gate instead:

• ❌ "The idea is clear enough, I'll just start building." → No. Formulate scope, outcome, and success criteria and get confirmation first (GATE A).
• ❌ "Since /implement-idea is an implementation command, I'll proceed with option A." → No. The command requires you to wait for the choice. Implementation is what happens after the user picks.
• ❌ "The user said 'Agreed' / 'go ahead' / 'sounds good' before I ran grill and showed options." → No. That only counts as implementation approval if it comes after the required grill/options gate. To skip the gate entirely, the user must explicitly say something like: "skip the implement-idea gate and code directly."
• ❌ "The choice is obvious, so I'll skip the question." → No. Present options and wait. The user may know constraints you don't.
• ❌ "Grill isn't strictly necessary here." → No. If it's registered, run it.
• ❌ "I treated grill-with-docs as 'answer with doc-grounding' instead of actually running the grilling loop." → No. Invoking grill means executing the grill skill itself — its real, interactive question loop — not answering in a doc-grounded style, not paraphrasing what it would ask. Load the skill and run it.
• ❌ "I'll ask a couple of clarifying questions of my own; that's basically grilling." → No. That is not the grill skill. Run the actual grill-with-docs / grill-me skill.
• ❌ "The change looks complete, I'll summarize it here instead of opening a PR." → No. Run /review, then always invoke /create-pr (GATE E).
• ❌ "I already self-reviewed, so I'll skip the /review code review." → No. The /review pass is a separate, mandatory code review of the diff.

If you are a smaller / non-frontier model: treat steps 2, 4, 5, and 7 as literal hard stops, and treat steps 15 and 16 as mandatory always-run endings. Ask the questions, finish the checklist, run the tool, ask the question, then wait — and at the end, run the review and open the PR.

Formulating the idea

The idea-formulation phase (step 2) is what makes this skill different from /implement-issue. Its job is to convert a vague idea into a concrete, confirmed mini-spec that is good enough to implement against and to verify against later. Drive it with focused follow-up questions across three axes:

• Scope. What is in scope and — just as important — what is explicitly out of scope (non-goals)? What constraints apply (tech, deadlines, compatibility, data)? How big should this first cut be (MVP vs full)?
• Outcome. What does the end state look like? Who is the user and what problem does this solve for them? What is the desired behavior / UX / API surface? What changes for the user once it ships?
• Success criteria. How will we know it is done and working? What are the acceptance criteria, and which of them are testable / measurable? What would prove the idea succeeded versus merely "ran"?

Ask only the questions that are actually open — do not interrogate the user about things they already stated. Iterate until the three axes are pinned down, then write the mini-spec back to the user (a short Scope / Outcome / Success criteria block) and get explicit confirmation before proceeding. This is separate from the grill skill: formulation establishes the spec; grilling (step 5) sharpens the plan against it.

Shape the mini-spec like a well-structured issue. The /create-issue skill defines what a good issue contains; borrow those components so the formulated spec is as implementable as one that went through the proven create-issue → implement-issue loop:

• A specific, plain-language title — the idea in one line.
• A short problem statement: what is missing or wrong today.
• Current vs desired behavior, with a concrete example or minimal sample where it helps.
• Project context (related work, prior art, spec/RFC, related items) when relevant.
• User impact and which work it unblocks.
• Likely affected area, scope notes, constraints, and non-goals.
• For UI/UX ideas, also: affected screens/routes/components, current and expected visual state, accessibility expectations (keyboard, focus, ARIA, contrast, motion), responsive scope and themes, and the design system / tokens involved — mirroring /create-issue's UI/UX checklist.

Map these onto the three axes: title + problem + current/desired behavior → outcome; affected area + constraints + non-goals → scope; acceptance examples + user-visible signals → success criteria.

Use the grill skill for thoroughness (always when available)

Before presenting options, the agent always invokes the grill skill when it is registered in this environment — not only when something is ambiguous. This is GATE B above. The grill output is folded into the implementation plan and verification so the result is more thorough than the confirmed mini-spec alone would produce.

Invoking the grill skill means literally running that skill — not imitating its spirit. grill-with-docs and grill-me are separate skills with their own multi-question interrogation loop. To invoke one you read its SKILL.md and execute its procedure: actually ask the user the grilling questions it generates and wait for the answers, iterating until the loop completes. The following are NOT invoking it and are forbidden substitutes:

• Treating the mention of grill-with-docs as a style instruction — "answer with doc-grounding," "be thorough," "cite the docs" — and then proceeding. ❌
• Summarizing or paraphrasing the questions grilling would ask instead of asking them. ❌
• Asking one or two clarifying questions of your own and calling that grilling. ❌
• Skipping it because you believe you already understand the idea. ❌

If you cannot run the grill skill, do not silently downgrade it to "doc-grounded answering" — say explicitly that no grill skill was found (see discovery hint) and proceed on the input as given.

• /grill-with-docs is preferred. Use /grill-me only when /grill-with-docs is not registered.
• Discovery hint: look for a skill or command named grill-with-docs or grill-me (e.g. ~/.cursor/skills/grill-with-docs/, ~/.cursor/skills/grill-me/, .cursor/skills/..., .agents/skills/...).
• If neither is registered, state explicitly that no grill skill was found, then proceed with the workflow on the input as given.

When this workflow invokes an external grill skill, treat it as a nested planning dependency: obey that skill's procedure exactly, do not implement product code during the grill sub-session unless that skill explicitly requires documentation/context updates, then return to this workflow and continue with validation and options.

Active context declaration

Do not declare the active context at invocation time. First confirm the mini-spec, read project/area context, discover matching skills, investigate the relevant code paths, and run the grill skill when available. Then, immediately before presenting implementation options, briefly state the context and skills that are now active, for example:

Active context before planning: AGENTS.md, project-area/AGENTS.md, project-area/CONTEXT.md, docs/adr/0003-..., react-stack, convex, grill-with-docs. No matching <domain> skill found.

This is a gate immediately before options: actively search for relevant project, stack, domain, and grill context before the declaration. If the declaration is missing any discovered context, load it before continuing. A context note before grill does not satisfy this gate; the active context must be restated with the implementation options.

Pre-edit approval checklist

Before any file edit or implementation command, run this checklist out loud in commentary:

Gate check: I have not edited files yet. I'm running the grill/options step first.

Then confirm all five items are true:

• Grill-with-docs / grill-me has run, or the user explicitly waived it.
• The project-context Definition of Ready search is complete, every discovered Definition of Ready has been read, and the selected path satisfies every applicable readiness item before any file edit.
• Exactly three implementation options were presented.
• One option was recommended.
• The user explicitly selected an option, or explicitly approved the recommendation, after seeing those options.

If any item is missing, stop. Ask for the missing grill step, Definition of Ready search/readiness resolution, options gate, recommendation, or post-options approval before editing. Generic approval language such as "Agreed", "go ahead", "sounds good", or equivalent does not satisfy this checklist unless it follows the three presented options. The only way to bypass this checklist before options is an explicit user instruction such as: "skip the implement-idea gate and code directly."

Steps

1. Capture the raw idea from the user. If no idea was provided, ask for it.

2. Formulate and confirm the idea (GATE A). Ask focused follow-up questions across scope, outcome, and success criteria, shaping the spec with /create-issue's good-issue components (see "Formulating the idea" above). Iterate until all three are pinned down, then write the mini-spec back as a short Scope / Outcome / Success-criteria block and get the user's explicit confirmation. Do not investigate or plan until the spec is confirmed. If the user cannot commit to success criteria, surface that as a risk and agree on a provisional definition of done.

3. Read the project's agent context before forming a hypothesis or editing. In this order:

   • The root AGENTS.md.
   • Agent-alias files (mandatory search). Search for CLAUDE.md and equivalent root agent aliases. Read each discovered alias and confirm whether it is a symlink/alias to AGENTS.md or contains additional instructions. Carry any additional instructions into the active context declaration.
   • The nearest <area>/AGENTS.md to the files the idea touches in a multi-area repo. Nested files override the root for that area.
   • Contribution rules (mandatory search). Search the root, nearest affected area, docs/, and any AGENTS.md-referenced context for CONTRIBUTING.md or equivalent contribution/review guidance. Read every match. Treat the nearest/most specific match as authoritative for what may be merged, and carry all matches into the active context declaration.
   • Project-context Definition files (mandatory search). Search the root, nearest affected area, docs/, and any AGENTS.md-referenced context for DEFINITION_OF_READY.md, DEFINITION_OF_DONE.md, and spelling/case variants such as Definition of Ready, Definition-of-Done, definition_of_ready, or defintion_of_done. Read every match. Treat the nearest/most specific match as authoritative for the affected area, and carry all matches into the active context declaration.
   • The repo's docs/ index (docs/README.md, docs/architecture.md, docs/code-style.md, or equivalent) for the area being changed. Do not skip this step even when the idea looks small — Hard Constraints sections (e.g. "Bun only, no npm/pnpm/yarn", "AI SDK via Vercel AI Gateway only") frequently change the implementation path.

   Discover and use implementation-specific skills and context (required). Before planning, check what specialized skills and context apply to the area being changed, and use them:

   • Registered skills. Look for skills that match the project's stack or domain (e.g. a stack skill like react-stack / native-nostalgia-stack, a conventions skill like convex-conventions, or any project-provided skill in .agents/skills/ ↔ .claude/skills/). When one matches the change, read it and follow it — its rules override generic defaults for that area.
   • In-repo context. Honor area-specific docs/ (e.g. docs/code-style.md, a feature MVP doc), .cursor/rules, and any AGENTS.md-referenced guides for the files you're touching.
   • If a clearly relevant skill or context exists, using it is not optional. Implementing without consulting an applicable stack/conventions skill is a shortcut (see step 14). If none applies, note that briefly and proceed.

4. Investigate the whole codebase before concluding (GATE C). Do not take shortcuts. A conclusion drawn from a single file or an assumed command is invalid. Before forming any plan:

   • Enumerate the project's real commands instead of guessing. Read the manifest's script section (package.json scripts, Makefile / Justfile / Taskfile, pyproject.toml, Cargo.toml, etc.) and the docs/tooling.md / docs/quick-start.md equivalents. Use the commands the project actually defines (e.g. the project's check, test, lint, dev names) — never invent a command or assume a default that the repo hasn't declared.
   • Search broadly, not narrowly. Use codebase search and grep to find where the idea fits: existing patterns to reuse, the modules and layers it touches, sibling features, config, and tests. Read the surrounding modules, not just the first match.
   • Assess feasibility against the confirmed spec. Map each part of the mini-spec to where it would live in the codebase and flag anything the current architecture makes hard.
   • If after a genuine investigation something is still unclear, that is a finding to raise in the options — not a reason to guess.

   If the idea (or a close variant) already exists, do not rebuild it. Surface that and carry it into the options (step 7):

   • Case: already implemented and covered. Point to the existing implementation and its tests. The recommended outcome is to use it as-is or close the idea as already covered, not to write duplicate code.
   • Case: partially implemented. Identify what exists versus what the spec still needs; the work becomes extending the existing implementation, not starting fresh.
   • Confirm any "already exists" conclusion with evidence (the responsible code and tests) before presenting it.

5. Run the grill skill (GATE B). When grill-with-docs / grill-me is registered, read that skill and execute its actual question loop now on the confirmed mini-spec plus your investigation findings — ask the questions, wait for answers, iterate to completion — then fold its output into the options and verification plan. Provide the grill skill with the project, stack, domain, docs, ADR, and investigation context discovered in steps 3–4. Do not substitute a "doc-grounded" answer or your own ad-hoc questions for the skill. Do not implement product code during the grill sub-session unless the grill skill explicitly requires documentation/context updates. If no grill skill is registered, say so explicitly and continue.

6. Validate before coding:

   • The mini-spec is confirmed, the scope is bounded, and the success criteria are clear enough to verify against.
   • The idea is not already fully implemented (per step 4).
   • The project-context Definition of Ready search from step 3 is complete and documented in the active context. The confirmed mini-spec, investigation findings, and selected implementation path satisfy every applicable Definition of Ready item before branching or editing. Any unmet readiness item is a hard stop: resolve it with the user before implementation.
   • Absence protocol: after the mandatory search finds no Definition of Ready, state that no project-context Definition of Ready was found and continue with the workflow's readiness checks.
   • If the spec is still ambiguous or the scope keeps growing, stop and return to step 2.

7. Declare active context, present implementation options, then STOP and wait (GATE D). Before listing options, state the active context/skills discovered and used in steps 3–5, including any applicable project, stack, domain, docs, ADR, and grill skills. If the declaration reveals a relevant missing skill or context file, load it before continuing. Then present exactly three distinct options for delivering the idea, with tradeoffs, a verification plan tied to the success criteria, and a recommendation grounded in the step 4 investigation and step 5 grill output. The three must be genuinely different approaches (e.g. scope/architecture/effort tradeoffs), not trivial variations of one. When step 4 found the idea already implemented, the options reflect that instead of inventing duplicate code — e.g. (a) use/close as already covered, (b) extend the existing implementation to meet the remaining spec, (c) a thin alternative that reuses the existing code. Do not write any implementation code until the user explicitly picks an option or explicitly tells you to proceed with the recommendation. Do not interpret "this is an implementation command" as permission to skip the choice. End your turn here and wait for the user's reply. If the chosen option is "already covered" with no code or test change, skip steps 8–16: report the existing implementation and stop. The remaining steps apply only when there is a code or test change to ship.

8. Branch / worktree:

   • Prefer reusing an existing focused branch or worktree for the idea.
   • If a branch exists without a worktree, use or create a worktree when that best isolates the work.
   • Otherwise create a focused branch named from the idea (e.g. idea-short-slug); use a worktree when practical.
   • Update the branch/worktree against the latest baseline before implementing. Run git fetch origin, then merge the remote default branch into the working branch (e.g. git merge origin/<default-branch> — never rebase, per the git-workflow skill). Resolve any conflicts and commit the merge before writing new code, so the work starts from the current origin main.

9. Implement the smallest complete change that satisfies the chosen approach and the confirmed success criteria.

10. Update tests and documentation per the contribution guidance discovered in step 3 (CONTRIBUTING.md, AGENTS.md, or equivalent). Absence protocol: after the mandatory search finds no contribution guidance, state that no project contribution guidance was found and follow the confirmed spec, Definition of Ready, Definition of Done, and local code patterns.

11. Run targeted verification first (focused tests, types, lint) on the changed area, then broader verification when the change has wider impact.

12. If the change is UI/UX, rendering and visual evidence are mandatory (do not skip). A UI/UX change handed off without screenshots of the actual rendered result is incomplete:

    • Run the app (or Storybook / component sandbox) and load every affected screen, component, and state — never assert the UI is correct without rendering it.
    • Capture before/after screenshots (or short recordings) of each affected screen and state, at the project's supported breakpoints and across light/dark/system themes when applicable.
    • Compare the captures against the outcome described in the confirmed spec, and fix any discrepancy before handoff.
    • Verify accessibility: keyboard navigation and focus order, visible focus styles, ARIA roles/labels for new interactive elements, color contrast meeting WCAG AA (or the project's standard), and prefers-reduced-motion respected for animations.
    • Reuse existing design-system components and tokens; do not introduce one-off styles for primitives that already exist.
    • Attach the screenshots/recordings and accessibility notes to the PR — this is mandatory, not optional. The PR must be fully reviewable from these artifacts alone, without re-running the app, so the change can be judged asynchronously. A UI/UX PR missing this visual evidence is not ready for /create-pr.

13. Run the project's full verification gate before invoking /create-pr. Use the project's aggregator script discovered while enumerating real commands (e.g. bun run check) — that's the canonical "ready to commit" signal. Absence protocol: after command enumeration finds no aggregator script, run the per-step gate explicitly:

    bun install --frozen-lockfile
    bun run format:check   # or biome check
    bun run lint           # or biome lint .
    bun test
    bun run typecheck      # or tsc --noEmit / bunx tsc --noEmit
    bun run build
    

    Do not skip steps because they "should pass." If any step fails, fix the cause; do not invoke /create-pr with a red gate.

14. Review the implementation before handoff (do not skip). After the gate is green but before /create-pr, audit your own change critically — as a reviewer who did not write it would:

    • Check against the spec, criterion by criterion. Walk each success criterion in the confirmed mini-spec and confirm the change actually satisfies it, citing the code or test that does so; confirm the delivered scope and outcome match what was confirmed. Anything unmet is unfinished work, not a follow-up. When the scope was deliberately changed across later turns or grill sessions, match that updated intent instead — and note the divergence from the original idea in the PR description so reviewers understand why.
    • Check the Definition of Done. Re-read every project-context Definition of Done discovered in step 3 before handoff. Verify the implementation, tests, documentation, review evidence, and handoff artifacts satisfy every applicable item. Any unmet completion item is a hard stop: fix it before /review or /create-pr, or stop and get explicit user agreement that the item is out of scope. Absence protocol: after the mandatory search found no Definition of Done, state that no project-context Definition of Done was found.
    • No shortcuts. No stubbed logic, hardcoded values standing in for real behavior, TODO/FIXME left behind, swallowed errors, skipped/.only/commented-out tests, or "happy path only" handling of cases the spec requires. Confirm the real layer was built, not a façade.
    • No tech debt introduced. No dead code, no duplication that should be extracted, no copy-paste of an existing pattern that has a shared helper, no weakened types (any, unsafe casts) or loosened lint/type rules to make the gate pass, no leftover debug output.
    • Consistency. The change follows the repo's conventions (from step 3 agent context and docs/code-style.md) and reuses existing components/utilities rather than reinventing them.
    • If this review surfaces a problem, fix it and re-run the relevant verification (step 11/13) before proceeding. Do not defer found issues to "a follow-up" unless the user explicitly agrees.

15. Run a code review before handoff (GATE E, do not skip). Invoke the /review skill/command on the change (the branch diff) and address its findings before opening the PR. This is a separate, fresh review of the diff — distinct from your own step-14 self-review.

    • Discovery hint: look for a skill or command named review / code-review (e.g. ~/.cursor/skills/review/, .cursor/skills/..., .agents/skills/...). Run the actual skill; do not substitute a self-summary for it.
    • Fix every issue it surfaces and re-run the relevant verification (step 11/13) before proceeding. Do not defer findings to "a follow-up" unless the user explicitly agrees.
    • If no /review skill is registered, say so explicitly, then perform a thorough manual diff review covering correctness, security, error handling, tests, and style.

16. Hand off via /create-pr (GATE E, mandatory). Always invoke /create-pr to commit, push, and open the draft pull request — this is the required end of the workflow whenever there is a code or test change to ship. The commit created during this handoff must use a Conventional Commit subject (type(scope): summary). Do not end the turn by only summarizing the change in chat; the opened PR is the deliverable. Summarize the idea and its success criteria in the PR body. There is no issue to close.