Fieldwork, value, engineering, and operations for AI that works beyond the demo.
An open-source design and verification kit for people building AI into real work: applied-AI engineers, product and workflow owners, service operators, and forward-deployed engineers (FDEs).
Five-minute field guide · Complete method · One worked engagement · 12 Factors of AI Value Engineering · Executive funding guide
Start with what went wrong
| 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 service handoff | The missing evidence or capability, its owner, and a repair, transfer, pause, or retirement decision |
| AI 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.
Use the 12 Factors and one-page scorecard to test the outcome, verifier, adoption, authority, cost, and proof. The executive funding route supports the investment decision.
See it working
Try the invoice practice packet: a messy brief, difficult documents and review rubric. Its runnable lab compares rules with optional model proposals.
The invoice-exception engagement follows a sold promise that field evidence kills: reframe, economics, controlled-write runtime, evaluation, blocked handoff, and review-only decision.
The shipment-risk example combines classical ML, deterministic routing, optional model explanation, and human review.
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
Internal teams may keep operating the service; FDEs may transfer it. Both need evidence of improvement and an owner when it breaks.
| 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
The canonical lifecycle:
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 with operating ownership"]
H --> I["Operate, learn, or retire"]
Each transition needs evidence and an accountable decision. A model score, sponsor, or deadline cannot override a failed value, authority, safety, ownership, or production gate.
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/applied-ai-field-guide
Pin the source. Skills grant no authority or evidence. Give an agent AGENTS.md.
The Applied AI Field Guide local plugin adds local continuity for sources, revisions, decisions, dependencies, and review packets. Keep restricted content in its approved source system; local execution is not permission to copy it.
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-ai-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 |
Confirm which skill the host selects.
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.