The FDE Guide

Field discovery, accountable adaptation, value engineering, and production architecture for real-world AI delivery

Open-source guidance for FDEs, applied-AI teams, and operators turning messy work into accepted, operated outcomes.

Five-minute field guide · Complete method · One worked engagement · 12 Factors of AI Value Engineering · Executive funding guide

Start with what went wrong

Pick the situation in front of you; don't learn the repository first.

What happened	Start here	Leave with
The brief doesn't match the real workflow	Field engagement and reframing	One representative case, conflicting claims, a safe fallback, and the person who may decide
Nobody can identify the real process owner or expert	Find the process knower and open an observation log	A named operator or owner and a recent exception followed end to end
The sponsor, operator, and policy disagree	Bound the conflict and use the reframe record	Cited evidence and an accepted, rejected, or deferred reframe
The team needs to prove one safe slice	Discovery and Value, then build one vertical slice	An accepted outcome, verifier, exclusions, maximum effect, and test cases
Something was built, but acceptance or ownership is stuck	Production readiness and customer handoff	The missing evidence or capability, its owner, and a repair, transfer, pause, or retirement decision
Agent pilots are multiplying without a clear operating model	Company operating model and workflow portfolio review	Named decision rights, shared rails, workflow-local accountability, proof gates, and temporary dependencies

Choose your depth

Layer	Use it for	Entry
The Guide	The mental model and canonical delivery loop	Five-minute Guide, then concise Guide
Handbook	Running a live engagement	Lifecycle playbooks
Engineering Kit	Contracts, controls, architecture, evaluations, operations, and executable evidence	Templates, controls, and examples

They are not separate frameworks. The capability roadmap is a learning route, not a certification.

The core idea

Start with the work and the accepted outcome, not a model or agent topology. Compare deterministic software, optimization, classical ML, retrieval, a foundation-model call, a bounded agent workflow, and human review. Choose the smallest mechanism that can safely do the job.

Tokens are an input. Autonomy is a design choice. Accepted outcomes are the product.

The 12 Factors of AI Value Engineering make outcome, verifier, adoption, authority, cost, proof, and lifecycle gates explicit. Use the one-page scorecard for a live decision. If you're deciding whether to release more money or time, use the executive funding route.

See it working

The invoice-exception engagement follows a sold promise that field evidence kills. It connects the reframe, worked economics, mechanism choice, controlled-write runtime, evaluation, adoption plan, blocked handoff, and review-only decision. Inspect the runtime and its adversarial tests.

The shipment-risk example combines classical ML, deterministic routing, optional model explanation, and human review without pretending every workflow needs an agent.

npm ci --ignore-scripts
npm run test:reference
npm run test:evals
npm run test:hybrid

These are in-memory teaching systems. Passing tests proves only the declared local behavior—not customer value, production readiness, or deployment approval.

Before adapting them, use Enterprise Integration and Scale Reality to replace teaching conveniences with target evidence.

Who this is for

You need to	Use
Fix an inherited brief or field contradiction	Five-minute Guide and reframing playbook
Decide whether the workflow is worth funding	Executive funding guide and 12 Factors worksheet
Deliver or operate the change	Handbook and the current lifecycle stage
Design or review the system	Engineering Kit, blueprints, and production controls
Learn or assess the practice	Capability roadmap and one bounded mission

From idea to production

This is the one canonical lifecycle. Shorter diagrams elsewhere are labeled field or capability views.

flowchart LR
    A["Inherit the brief"] --> B["Observe and reconcile the work"]
    B --> C["Charter value and scope"]
    C --> D["Make data fit for the decision"]
    D --> E["Select the mechanism"]
    E --> F["Build one controlled slice"]
    F --> G["Prove it with cases and users"]
    G --> H["Launch and transfer ownership"]
    H --> I["Operate, learn, or retire"]

Loading

Each transition needs inspectable evidence and an accountable decision. A model score, sponsor, deadline, or renewal cannot average away a failed value, authority, safety, ownership, or production gate. Follow the complete method or read the worked invoice chain.

Validate a working artifact before it is complete:

npm run validate:artifact -- ./path/to/workflow-start.json --profile starter --type workflow-charter
npm run validate:artifact -- ./path/to/workflow-charter.json --profile complete

The starter profile checks the few fields needed for the current decision while retaining the same canonical types and closed-object rules. It is not a second schema. See artifact validation.

Start from a business flow

After workflow and value are accepted, choose a business-flow pattern and, when material, an industry profile. Add only needed foundations. The solution portfolio remains a design hypothesis, not evidence or a deployable product.

Optional: use it with a coding agent

The guide is complete as documentation. Sixteen optional skills provide focused routes over the same canonical artifacts:

npx skills add davidahmann/fde-guide

Pin the source. Skills grant no authority or evidence. Give an agent AGENTS.md.

The private FDE local plugin adds offline continuity for sources, revisions, decisions, dependencies, and review packets. Keep restricted content in the customer system.

Describe the situation; don't translate it into repository taxonomy first:

Say this	Intended route
“Keep this engagement coherent and tell me the next defensible move.”	$run-fde-engagement
“The brief is wrong, and sponsor and operator disagree.”	$reframe-ai-engagement
“We bounded the workflow. Is it worth funding?”	$engineer-ai-value
“This exact release is ready for a production decision.”	$review-ai-production-readiness
“The service is live; decide what to improve, constrain, or retire.”	$operate-ai-service

These cues don't prove host routing. Confirm the skill.

Scope and contribution

The control catalog is project policy, not an external compliance standard. Target organizations retain architecture, risk, and release authority.

Contributions should improve an existing route before adding another one. See CONTRIBUTING.md, repository maintenance, security policy, and the Apache-2.0 license.