One contract. Four backends.
34 shared test cases. A CI workflow that runs them against the TypeScript, Python, Rust and C++ todo backends.
Agent-First Development
Open source.Open to a new kind of user.
Commands are the product.
Change the interface.
Keep the software.
Live / local to this tab
AGENT / scripted
Same tools.
Same tools.
Different operator.
Ready to take a turn.
COMMAND LAYER
CLItodo-listsuccess
Ready.
Different surfaces. One shared state.Your app isn't
its buttons.
It's what those buttons do. Put that capability in a command, and a screen becomes a choice. So does a terminal. So does an agent.
Keep business logic out of the screen. Don't build a second API just to let an agent in.
Fig. 02The handoff
Your turn.
Your turn.
Their turn.
An agent shouldn't have to pretend to be a person clicking a button. Give it the same capability, directly.
Scripted agent. Real commands. No model or account needed.
Agent sessionSTANDBY
“Give me a capability.
I'll take it from here.”
-
01
waiting
todo-listRead the shared state.
-
02
waiting
todo-createCreate the requested task.
-
03
waiting
todo-listVerify the result.
Waiting for your handoff.
Back to the shared list
Fig. 03Design for the agent
Access isn't enough.
Access isn't enough.
Agents need good UX.
A person gets labels, feedback and a chance to change their mind. An agent deserves the same care in its command contract.
- Make intent legible.
- Named capabilities, typed inputs and explicit prerequisites.
- Return more than data.
- Reasoning, warnings and a useful next step when something fails.
- Keep people in control.
- Confirm consequential actions. Offer undo where possible. Say when it isn't.
A person discovers what an app can do by looking at its menus. An agent reads
the contract.
- Purpose
- Inputs
- Effects
Full command contract
Know what a command takes, what it does and whether it changes state before calling it.
LATEST LIVE RESULT
todo-list
A person gets feedback on screen. An agent gets reasoning and a next step in
the result.
- Outcome
- Reasoning
- Confidence
- Next step
Full command result
Reasoning explains the outcome. Confidence is a signal, not permission to act.
todo-clearDESTRUCTIVE
A person gets a confirmation dialog. An agent’s caller gets the same
pause.
A pause before
the point of no return.
Delete the shared demo tasks in this tab. No undo.
No deletion requested.
This caller asks before execution. Destructive metadata describes risk; it doesn't enforce authorization.
Fig. 04The recovery
A dead end.
A dead end.
Or a way forward.
“Something went wrong” isn't an answer. A useful error tells the next operator what to do.
REQUEST / READYtodo-create
{ "title": "", "priority": "high" }
What comes back matters.
// No title. No task.
// The command will explain what's missing.
THE DIFFERENCE
An error can be the next step, not the last one.
Fig. 05The honesty check
“If it can’t be done via CLI, the architecture is wrong.”
One rule, applied to every feature. No UI-only code paths.
Fig. 06Build with an agent
Before it draws a screen,
Before it draws a screen,
give it something to prove.
A BRIEF FOR YOUR CODING AGENT
Build the capability.
Prove the job works.
Then design the interface.
A coding agent can implement a typed command, call it from the terminal and verify the result before a single component exists. The UI comes after the behavior is real.
Read the AFD skill-
01
Define the contract.
todo-createtakes a title and priority, returns a structured result, and rejects missing input. -
02
Exercise both paths.
Call the command with an empty title, then a valid one. Verify the error is actionable and the task is created.
-
03
Test the whole job.
Create a task, list it, check the outcome. A scenario tests the user's goal across commands.
-
04
Give it a surface.
Connect the form to the proven command. Keep the rules in the command layer, not in the component.
Don't take it
on faith.
INSPECT THE WORK
Test a job, not just a function.
Readable YAML scenarios express a goal, command steps and expected outcomes. Start with creating and verifying a task.
Read the scenario
Used to build its own tools.
Alfred checks AFD architecture, language parity and command quality through CLI and MCP, returning CommandResult.
Meet Alfred
Fig. 07Start small
Start with one command.
Start with one command.
Keep your stack.
Packages, not a platform. Add AFD to your stack, one capability at a time.
Install the library.
npm install @lushly-dev/afd-server @lushly-dev/afd-cli zodpip install afdcargo add afdinclude(FetchContent)
FetchContent_Declare(afd GIT_REPOSITORY https://github.com/lushly-dev/afd.git
GIT_TAG cpp-v0.1.0 SOURCE_SUBDIR packages/cpp)
FetchContent_MakeAvailable(afd)
target_link_libraries(my_app PRIVATE afd::afd)Give your coding agent the method.
Add the AFD skill to your project: command design, validation and the define-validate-surface workflow.
npx degit lushly-dev/afd/.claude/skills/afd .claude/skills/afd
Fig. 08Your turn