gilde

← All craftbooks

gRPC Service

Build: software and codeevalv1.0.0released 2026-06-05workflow: build-loop

Build a gRPC service from a Protocol Buffers contract — define the .proto service and messages, implement the server handlers, and verify with client calls including streaming and status codes. Designs the proto contract FIRST — the service, RPC methods, request/response messages, field numbers, and the streaming kinds — because the .proto is the binding contract across languages, then implements the handlers, then tests unary/streaming calls and gRPC status codes. Covers protobuf service/message definitions, field numbering, unary vs server/client/bidi streaming, gRPC status codes, deadlines, and a client-driven test.

Steps

Entry step: proto-design. Each step names the specialist role it wants; the full working prompt is expandable.

  1. Proto contract designplannerentry

    lock the service, methods, messages, streaming kinds

    Show working prompt
    Design the Protocol Buffers contract before any server code — the .proto is the binding cross-language contract. Step 1: Define the service and its RPC METHODS, choosing the streaming kind for each (unary, server-streaming, client-streaming, bidi). Step 2: Define the request and response MESSAGE types with explicit, stable FIELD NUMBERS and correct scalar/enum/repeated types. Step 3: Decide the gRPC STATUS-CODE map: which conditions return OK, INVALID_ARGUMENT, NOT_FOUND, ALREADY_EXISTS, etc., and how errors carry detail. Step 4: Note deadlines/timeouts expectations. Step 5: Write a numbered acceptance-criteria checklist of 5-9 items (e.g. 'each RPC has the documented signature and streaming kind', 'invalid input returns INVALID_ARGUMENT not OK', 'a missing entity returns NOT_FOUND', 'field numbers are stable and unique'). `write_task_note` the proto draft + status map + checklist and write the same to the produces path.
  2. Build the servicedeveloper

    write the .proto + implement the server handlers

    Show working prompt
    Implement the gRPC service to the contract. Step 1: Write the `.proto` file exactly as designed — service, methods with their streaming kinds, and messages with their field numbers. Step 2: Implement a server handler for every RPC; honor the streaming kind (stream responses for server-streaming, consume the stream for client-streaming). Step 3: Validate requests and return the correct gRPC STATUS CODE on each error condition (INVALID_ARGUMENT, NOT_FOUND, ...), never a generic UNKNOWN for an expected error. Step 4: Respect deadlines and use an in-memory store if none specified. Write the server source to the produces path (and the .proto alongside it). On a loop-back, fix only the named gaps. `write_task_note` the file paths and which criteria now pass.
  3. Test with a clientdeveloper

    test unary/streaming calls and status codes

    Show working prompt
    Write client-driven tests against the running service. Step 1: For each unary RPC, call it and assert the response message matches the proto and the status is OK. Step 2: For streaming RPCs, drive the stream and assert the sequence of messages is correct. Step 3: Trigger each error condition and assert the correct gRPC STATUS CODE comes back (INVALID_ARGUMENT on bad input, NOT_FOUND on missing), not OK or UNKNOWN. Step 4: Add a round-trip (create then fetch) to prove state wiring. `write_task_note` the test file path and pass/fail count.
  4. Evaluatereviewer

    Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

    Show working prompt
    Run the tests with a gRPC client. For EACH acceptance criterion: confirm each RPC's signature/streaming kind works and unary responses match the proto, confirm streaming RPCs yield the right message sequence, confirm error conditions return the correct gRPC status code (not OK/UNKNOWN), and confirm a round-trip works. Write PASS/FAIL per criterion.

Then route — this is the whole point of the loop:

- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "build" })` to loop back. The builder fixes exactly those gaps.

Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.
  5. Finishdeveloper

    All acceptance criteria met. Stamp a short summary and report DONE.

    Show working prompt
    Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license