CRUDDY controllers

CRUDDY controllers is an engineering skill installed by Flow. In this guide, you will learn:

• What engineering skills are and how they differ from the workflow skills
• The problem CRUDDY controllers solves
• How the skill runs and what it produces

Overview

Alongside the spec-driven workflow, Flow installs engineering skills: focused skills that each encode one specific AdonisJS design discipline. Where a workflow skill drives a change from brief to archive, an engineering skill answers a single recurring design question well, every time. You can invoke an engineering skill on its own, and the workflow skills pull one in when they reach a decision it owns.

cruddy-controllers is the first engineering skill. It designs and names AdonisJS controllers and routes on one rule: every controller maps to a single resource and exposes at most five RESTful methods. When a design needs a sixth, custom method, that is the signal that a new resource is hiding inside the controller.

The problem it solves

Feature requests arrive as verbs. "The user logs in." "The admin approves the request." "We send an invite." An engineer naturally turns each verb into a controller method: login(), approve(), sendInvite().

Followed far enough, that path produces sprawling controllers full of custom verbs. Custom verbs resist everything the rest of AdonisJS does consistently: authorization, validation, and routing all assume resourceful actions. The controller becomes a bag of loosely related procedures.

CRUDDY forces every action back to a resource and a RESTful verb. A verb that will not map to one of the five methods is a noun in disguise: login is the creation of a session, approve is the creation of an approval, cancel is the creation of a cancellation. Each disguised noun becomes its own controller. Once every action is resourceful, validators, transformers, policies, and routes snap into place around it.

The five methods

A CRUDDY controller uses only these method names:

There is no sixth name. An action that wants confirm, approve, cancel, or subscribe is creating a confirmation, an approval, a cancellation, or a subscription, and belongs in its own controller as store.

How to use it

The skill ships in per-stack variants, so the version in your project designs controllers for your rendering stack. It runs two ways.

You can invoke it directly when you are naming, scaffolding, splitting, or refactoring controllers and routes:

/flow-cruddy-controllers

The agent may also reach for it on its own when it recognizes that kind of task, and the blueprint skill calls it during planning whenever a change introduces a controller or a route. However it starts, the skill runs the same interview.

The interview

The discipline lives in the interview, so the skill always runs it rather than naming controllers in one shot. It walks a fixed set of steps, one question at a time:

• Name the resource. The skill pins down the singular noun the controller is about, translating any verb the request was phrased as back into its noun.
• List every action a client can take on that resource, then map each action to one of the five methods.
• Identify state transitions. For each action that changes the resource's state, the skill works out whether the transition is implicit (the same update with a different value in the payload) or explicit (its own endpoint with its own semantics).
• Decide the splits. When two or more transitions each need their own endpoint, the skill applies a shared-thing test to decide whether they collapse into one resource controller or each become a controller of their own.
• Define the routes. Routes express client-facing URLs and do not have to match controller names. A POST /login route can map cleanly to SessionsController.store.

POST   /login    → SessionsController.store
DELETE /logout   → SessionsController.destroy

At each stage the skill presents its proposal and waits for your confirmation before moving on.

What it produces

CRUDDY controllers produces a design, not code. Run on its own, it returns the final route table: HTTP method, URL path, and the controller method each route maps to. Invoked from the blueprint skill, it hands back a structured list of controllers and their methods for the blueprint to plan against. Generating the controller files is left to the build step or to you.

Next steps

• See Spec-driven development for the workflow that calls this skill during planning.
• See your agent's guide for the exact command syntax.