The FDE Guide

Value engineering and production architecture for FDEs, applied AI engineers, product teams, and operations leaders

An independent, open-source field guide for FDEs and internal applied-AI teams moving a customer or internal workflow from discovery to a measurable, operated outcome.

Use it to:

• Find operational work where a software system can create measurable value—and reject weak use cases early.
• Choose the smallest adequate mix of rules, optimization, ML, foundation models, agents, and human review.
• Turn field observations into a clear workflow, architecture, delivery plan, and controlled production service.
• Give operating and engineering teams the evidence, ownership, and routines to maintain the result.

Start here

Choose the path that matches the work in front of you:

If your coding agent does not discover repository-local skills, give it AGENTS.md as the working map and name the relevant SKILL.md explicitly.

Skill library

The repository includes ten focused, repository-local skills under .agents/skills/. Each one is a thin workflow over the same controls, templates, and playbooks humans can read directly.

In hosts that support explicit skill invocation, start with a prompt such as:

Use $qualify-ai-workflow to assess this candidate workflow: [describe it].

The skills are instruction-only: they do not grant tools, credentials, permissions, or approval. The control catalog, schemas, target-system policy, and human authority remain controlling. Pin the repository release or commit you reviewed; before admitting a skill into a production workflow, apply the provenance, authority, lifecycle, and disable controls in TOL-006.

The promise

From a real workflow to a measurable, operated outcome.

A useful demo can call a model and a few tools. A production AI-enabled system must also know who is allowed to act, which information is current, how to handle failure, how to prove that work finished, how much it costs, and how operators can stop or recover it.

In this guide, a production agent is a bounded workflow in which a foundation model makes some decisions, software controls tools and state, and people remain accountable for the outcome. An agent is one component option—not the default answer for every decision.

This repository provides the design sequence, reusable contracts, tests, and operating checks around that system. It does not require a specific model, cloud, or agent framework. It is not a drop-in runtime, a certification, or a substitute for your organization's security and risk review.

Value engineering is the spine

Work in this order: outcome → workflow → decision → system → controlled action → accepted result → measured value. Start with the user's operational decision and the economics of an accepted result. Only then choose the software architecture and the smallest adequate intelligence mechanism. The value-engineering guide and intelligence-selection guide are the two starting points for that work.

From idea to production

The repository follows one delivery path. Each stage produces an artifact that the next stage can inspect or test.

flowchart LR
    A["Observe the work"] --> B["Charter value and scope"]
    B --> C["Select the decision mechanism"]
    C --> D["Build one controlled slice"]
    D --> E["Prove it with cases and users"]
    E --> F["Launch with owners and rollback"]
    F --> G["Operate, improve, or retire"]

Draft the threat model before the evaluation suite, then refine both together as failure paths become concrete. If the workflow has no measurable outcome or trustworthy verifier, stay in discovery. A more capable model does not repair an undefined task.

Learn from the reference systems

The invoice-exception example shows the controlled-write method on a small financial workflow:

1. Read an invoice and the current policy.
2. Propose a resolution without giving the model authority to commit it.
3. Validate the proposal and stage it for approval.
4. Bind approval to the exact proposal.
5. Recheck permission and the current policy at commit time.
6. Make duplicate retries safe.
7. Verify the result in the ledger before reporting completion.

It includes machine-readable design files, a behavior bundle, tool and capability contracts, a threat model, executable policy, behavioral tests, adversarial evaluation cases, and a review-only release manifest. It is an in-memory teaching reference, not a deployable production service. Use the checkout validation to run it.

The shipment-risk triage walkthrough is the complementary end-to-end FDE reference. It follows an illustrative customer workflow through discovery, value measurement, intelligence selection, system design, adoption, handoff, and operation. Its compact executable core combines an ML risk score, deterministic routing, optional foundation-model explanation, and human dispatch review—without autonomous shipment intervention.

Choose the smallest system shape

Start with a deterministic workflow when the steps and branches are already known. Use optimization for constrained allocation, classical ML for measured predictions, retrieval for governed evidence, and human review for weakly verifiable or high-stakes judgment. Add an agent only where bounded multi-step judgment is useful. Add multiple agents only when a real permission, context, ownership, or latency boundary justifies the coordination cost.

Production rules in plain language

• A model may propose an action; trusted software must authorize and execute it.
• Keep the acting principal unambiguous: bind interactive work to the current user with agent attribution, and give unattended work its own narrow workload identity.
• Keep credentials behind a trusted tool boundary and restrict where runtime traffic can go.
• Admit tools, MCP servers, skills, CLIs, and code packages by verified publisher, pinned build, digest, authority, assurance, and lifecycle—not by name alone.
• Treat retrieved documents, user input, tool results, and memory as data—not instructions with higher authority.
• A retry of the same business operation must not create a second real-world change.
• After a consequential change, check the system of record before claiming success.
• Limit steps, time, retries, parallel work, and cost; every run needs an explicit stop reason.
• Treat cost as a non-functional requirement: measure full cost per accepted outcome and prefer the smallest mechanism that satisfies the outcome and risk ceiling.
• Keep evaluation data and pass signals outside the agent's control.
• Capture enough evidence to explain, pause, recover, and improve the workflow.
• Pass work between agents or context windows through a typed, expiring, authority-reducing handoff—not a free-form summary.

The machine-readable control catalog contains the repository's engineering baseline, with each requirement mapped to release gates. The evaluation-report and solution-release contracts make the tested claim and compatible release bundle explicit. This is project guidance, not an external compliance standard.

Repository map

The production AI-systems mind map shows how customer value, architecture, intelligence selection, context, control, evidence, adoption, and operations depend on one another. The FDE and applied AI engineering synthesis explains how field delivery and internal product/platform engineering share one lifecycle without transferring customer-specific context.

Evidence and scope

The guide combines practice-informed patterns with technical sources. The foundational source index distinguishes supplied summaries, supplied full text, and directly reviewed references. The dated research ledger covers implementation sources reviewed from 2026-02-07 through 2026-08-07, plus explicitly revalidated foundations, and records caveats alongside portable findings. A separate practitioner-video index records exact talks, chapters, corroboration, and claim limits.

Vendor scale and performance figures remain attributed. Experimental findings remain labeled. Platform behavior changes, so apply the same controls to your own environment and verify claims against current primary documentation before deployment.

Validate a checkout

Requires Node.js 22 or later.

Review repository code before running it. For an untrusted contribution, use CI or a disposable environment with no credentials or sensitive data; npm test executes repository-controlled code.

npm ci --ignore-scripts
npm test
git diff --check

The suite checks repository links and anchors, JSON contracts, policy denials, authorization boundaries, duplicate-safe writes, adversarial scenarios, traces, and postcondition verification in the reference environment.

Use this repository with a coding agent

Start with the closest skill in the skill library. Each skill progressively loads only the playbook, controls, templates, and examples needed for its job. AGENTS.md remains the repository-wide working contract: it explains authority, change routes, safety boundaries, and completion checks. catalog.json is the governed-artifact registry; llms.txt is the compact navigation index.

A useful fallback when no single skill fits is:

Follow AGENTS.md. Help me design a production AI-enabled system for [workflow].
Start by observing and chartering the current work: actor, decision,
inputs, action, owner, baseline, accepted outcome, verifier, adoption path,
and risk ceiling. Compare deterministic, optimization, ML, retrieval,
foundation-model, agent, and human options. Recommend the smallest matching
blueprint. Produce only the artifacts justified by the workflow, citing
repository control IDs. Do not begin implementation while a consequential
discovery question is unresolved.

For an implementation or review task, state the target workflow, allowed authority, systems in scope, evidence available, and expected deliverable. The skill or agent map can then route through the repository without loading every document.

Contribute

Start with CONTRIBUTING.md. Use GitHub Discussions for design questions, Issues for reproducible defects or evidence corrections, and the private vulnerability channel in SECURITY.md for security reports.

Maintained by David Ahmann (LinkedIn), a cloud, data, and AI platform leader with Field CTO experience. This is an independent project; no current or former employer endorsement is implied.

Licensed under Apache-2.0. Citation metadata is in CITATION.cff.