afd-developer

name

afd-developer

description

Agent-First Development methodology for building software where AI agents are first-class users. Covers command design, CLI validation, MCP servers, CommandResult schemas, testing strategies, and the core AFD philosophy. Use when: building agent-ready apps, designing commands, integrating MCP, understanding AFD patterns, or following the command-first workflow. Triggers: agent-first, AFD, command-first, MCP server, CommandResult, CLI validation, afd call, honesty check, define-validate-surface.

Agent-First Development (AFD)

Expert guidance for building software with the Agent-First Development methodology.

Routing Logic

Request type	Load reference
Philosophy, UX design for agents, "why AFD"	references/philosophy.md
Trust, CLI validation rationale, honesty check	references/trust-validation.md
Implementation phases, checklists, anti-patterns	references/implementation-phases.md
Output schemas, contexts, tool strategies, discover-detail-call workflows	references/implementation-phases.md
Production: security, observability, mutation safety	references/production-considerations.md

Core Philosophy

"The best UI is no UI" - AFD inverts traditional development where UI is built first. Instead:

Traditional:  UI -> API -> Agent Access (afterthought)
Agent-First:  Commands -> Validation -> UI (surface)

The Honesty Check

"If it can't be done via CLI, the architecture is wrong."

This principle ensures:

• No UI-only code paths
• All business logic lives in command handlers
• UI is a thin wrapper over commands
• Same commands power both human UI and agent interactions

Functional Parity, Not Literal Symmetry

AFD implementations SHOULD aim for the same capability set and agent-visible behavior across languages, but the public API MAY be idiomatic to the host language.

• Framework-agnostic command surfaces MUST stay framework-agnostic.
• React or browser integration SHOULD stay in examples or ecosystem layers.
• Cross-language ports MAY rename helpers, adjust signatures, or reshape modules when that improves language fit without changing behavior.
• Keep shared parity decisions aligned around agent-visible features such as output schemas, validated examples, prerequisite metadata, context scoping, grouped/lazy tool strategies, and meta-tools like afd-call, afd-batch, afd-pipe, afd-discover, and afd-detail.

Development Workflow

+---------------------------------------------+
|  1. DEFINE                                  |
|  - Create command with Zod/Pydantic schema  |
|  - Define inputs, outputs, error codes      |
|  - Add planning metadata: examples, requires, contexts |
|  - Choose exposure/discovery strategy       |
|  - Register in command registry             |
+---------------------------------------------+
              |
              v
+---------------------------------------------+
|  2. VALIDATE                                |
|  - Test via CLI: afd call <command>         |
|  - Inspect afd-help / afd-discover / afd-detail output |
|  - Run surface validation for the agent contract |
|  - DO NOT proceed until CLI works           |
|  - Add automated tests                      |
+---------------------------------------------+
              |
              v
+---------------------------------------------+
|  3. SURFACE                                 |
|  - Build UI that calls command              |
|  - Use metadata for UX (confidence, etc.)   |
|  - Preserve context/tool-strategy behavior  |
|  - Integration testing                      |
+---------------------------------------------+

Discovery Contract

For large command surfaces, the default agent workflow is:

1. discover candidate commands
2. inspect schemas and examples
3. call the chosen command

In AFD terms that usually means afd-discover -> afd-detail -> afd-call. afd-call, afd-batch, and afd-pipe are universal runtime tools, while individual, grouped, and lazy strategies control how the rest of the surface is exposed.

Command Structure

Naming Convention

Format: domain-action (lowercase, hyphen-separated)

Good:                    Bad:
todo-create              createTodo (not namespaced)
user-authenticate        todo_create (wrong separator)
document-search          TodoCreate (not lowercase)
todo.create              (dots not compatible with all MCP clients)

CommandResult Schema

Commands return structured results with UX-enabling metadata:

interface CommandResult<T> {
  // Core fields (required)
  success: boolean;
  data?: T;
  error?: CommandError;

  // UX-enabling fields (recommended)
  confidence?: number;      // 0-1, for reliability indicators
  reasoning?: string;       // Explain "why" to users
  warnings?: Warning[];     // Alert to side effects
  suggestions?: string[];   // Guide next steps
  sources?: Source[];       // Attribution for verification
  plan?: PlanStep[];        // Multi-step visibility
  alternatives?: Alt<T>[];  // Other options considered
}

Error Structure

Errors must be actionable:

interface CommandError {
  code: string;           // e.g., 'NOT_FOUND', 'VALIDATION_ERROR'
  message: string;        // Human-readable description
  suggestion?: string;    // How to recover
  retryable?: boolean;    // Can the operation be retried?
}

Standard Error Codes

Code	When to use
NOT_FOUND	Resource doesn't exist
VALIDATION_ERROR	Input fails schema validation
FORBIDDEN	User lacks permission
CONFLICT	Resource state prevents action
RATE_LIMITED	Too many requests
INTERNAL_ERROR	Unexpected server error
NO_CHANGES	Update had nothing to change

CLI Commands

# Connect to MCP server
afd connect http://localhost:3100/sse

# List available commands
afd tools

# Call a command
afd call todo-create '{"title": "Test", "priority": "high"}'

# Interactive shell
afd shell

AFD Packages

Package	Purpose
@lushly-dev/afd-core	Core types (CommandResult, CommandError, validateCommandName)
@lushly-dev/afd-server	Zod-based MCP server factory
@lushly-dev/afd-client	MCP client with SSE/HTTP transports + DirectClient
@lushly-dev/afd-testing	JTBD scenario runner, test validators
@lushly-dev/afd-adapters	Frontend adapters for rendering CommandResult
@lushly-dev/afd-cli	Command-line interface

When Adding Features

1. Define the command first - Create the tool definition with clear schema
2. Test via CLI - Validate it works before any UI work
3. Document the command - Add to tool registry with description

When Fixing Bugs

1. Reproduce via CLI - Can you trigger the bug without UI?
2. Fix at command layer - The fix should work for both agents and humans
3. Verify via CLI - Confirm fix works before checking UI

Testing Strategy

Layer	Tool	Purpose
Unit	Vitest	Test handler logic in isolation
Validation	Vitest	Test schemas accept/reject
Performance	Vitest	Baseline response times
AFD Compliance	Vitest	Verify CommandResult structure
Integration	Vitest	Test command -> store flow
E2E	Playwright	Test UI -> command -> response

Related Skills

• afd-typescript - TypeScript implementation patterns
• afd-python - Python implementation patterns
• afd-rust - Rust implementation patterns
• pr-review - PR review using AFD standards
• commit-messages - Conventional commit format

Resources

• Philosophy - UX design for AI collaborators
• Trust Through Validation - Why CLI validation matters
• Implementation Phases - Phased rollout with checklists
• Production Considerations - Security, observability, mutation safety