develop-handler

Implements one Connect-RPC handler through a TDD cycle of failing API test, implementation, and refactoring.

Updated Sep 14, 2026
One-click install
npx skills add https://github.com/nakamori-naoya/go-convention-plugins --skill develop-handler-nakamori-naoya
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: develop-handler
Source: https://github.com/nakamori-naoya/go-convention-plugins/tree/main/plugins/go-convention/skills/develop-handler
Command: npx skills add https://github.com/nakamori-naoya/go-convention-plugins --skill develop-handler-nakamori-naoya

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? It removes ambiguity about how to build a Go handler layer RPC with test-driven development by enforcing a fixed cycle: write the API test first, confirm it fails for the right reason, implement the minimal server code, confirm green, then align with language, error, and logging conventions. ## Core Features & Use Cases - TDD cycle orchestration: Runs one RPC as a single unit through fix-unit, write-failing-test, run-red, implement, run-green, refactor, align-errors, align-logs, and report steps defined in playbook.yml. - Convention delegation: Delegates test shape to the handler test convention, implementation form to the handler implementation convention, and error/log alignment to their respective conventions without redefining them. - Stop and resume conditions: Classifies red-test failure reasons, refuses to proceed on unrelated failures, and reports completed steps and open decisions when stopped. - Use Case: Given a proto service with a ConfirmReservation RPC and a finished usecase, ask the agent to implement that RPC via TDD; it writes the API test against a production-equivalent server assembly, watches it fail, implements the server method and conversion functions, and refactors to conventions. ## Quick Start Ask the agent to implement this RPC with TDD, writing the API test first and confirming red before implementing the handler.

Frequently Asked Questions about develop-handler

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I implement a Connect-RPC handler with TDD in Go?▼

Write the API test first against a production-equivalent server assembly, confirm it fails because the RPC method or conversion is missing, then implement the minimal server method and conversion functions until the test passes. This skill orchestrates that exact red-green-refactor cycle for one RPC at a time.

What is the scope of one TDD unit for a Go handler layer?▼

One unit is a single RPC from a proto service paired with the single usecase it calls. Other RPCs in the same service are handled as separate units after the current one closes green.

Does this handler TDD workflow require Docker?▼

Yes, the API tests run against a real assembly using dockertest with pgx/v5, so a running Docker daemon is a prerequisite. A missing Docker environment is classified as an invalid red and stops the cycle.

Why does the run-red step stop instead of proceeding to implementation?▼

It stops when the failure reason is not the target being unimplemented, such as missing Docker, red usecase tests, or unrelated test failures. Those causes are returned to the appropriate layer's entry point rather than masked by new handler code.

When should I not use this handler development workflow?▼

Do not use it when the RPC requires two usecases, no usecase exists yet, or lower-layer tests are not green. Those cases are returned to the usecase unit or other layer entry points first.