name: openfde description: Run a local-first environment discovery and deployment preflight on any repository using the OpenFDE CLI (fde init/scan/map/check/report). Use when asked to assess deployment readiness, map integrations, audit an unfamiliar customer codebase, or generate an FDE engagement report. license: Apache-2.0

OpenFDE — Deployment Preflight Skill

OpenFDE is a local-first CLI for Forward Deployed Engineers. It scans a repository, maps its integrations into a graph, runs explainable deployment-readiness checks, and produces a shareable Markdown report — fully offline, with file-level evidence for every finding.

Use this skill when the user wants to:

• understand what is actually inside an unfamiliar repository (runtimes, infra, data stores, AI providers, observability, auth);
• check whether an AI system is safe to deploy (PII policy, human approval boundaries, evals, retries/fallbacks);
• generate an integration graph (JSON + Mermaid) of the codebase;
• produce a deployment-readiness report to review with a customer.

Capabilities

Every check explains why it fired and which evidence produced it — no opaque AI scoring.

Installation

Requires Node.js 20+.

git clone https://github.com/GoldenOwlAsia/open-fde.git
cd open-fde
pnpm install        # or: npm install
pnpm build          # or: npm run build
npm link            # makes the `fde` command available globally

Or run directly from the checkout without linking:

npm run dev -- <command> [path-to-target-repo]

How to use (agent workflow)

Run the full preflight from the root of the target repository:

fde init      # once per repo — creates fde.yaml and .fde/
fde scan      # discover components
fde map       # build the integration graph
fde check     # run readiness checks
fde report    # write .fde/report.md

Then:

1. Read .fde/report.md and summarize the readiness score, critical findings, and warnings for the user.
2. If checks flag missing declarations (PII policy, human approval boundaries, eval suites, retry/fallback policies), offer to edit fde.yaml — the engagement spec under spec.constraints, spec.systems, and spec.successMetrics — and re-run fde check.
3. Use .fde/environment/integration-graph.mmd when the user wants a visual architecture map (it is standard Mermaid).

The engagement schema is documented in docs/FDE_SCHEMA.md and validated by schemas/fde.schema.json.

Safety notes

• OpenFDE is local-first: it never uploads source code, .env files, secrets, or scan output.
• Scanning is deterministic and read-only; the only writes are inside .fde/ and the starter fde.yaml.
• Do not commit customer-sensitive values into fde.yaml; declare constraints, not credentials.

Supported AI assistants

• Claude Code (use as an Agent Skill or invoke the CLI directly)
• Codex CLI
• Cursor / Cline-derived agents
• ChatGPT and other assistants with shell access (drive the CLI and read the .fde/ artifacts)

Links

• Repository: https://github.com/GoldenOwlAsia/open-fde
• Architecture: docs/ARCHITECTURE.md
• Engagement schema: docs/FDE_SCHEMA.md
• Security model: docs/SECURITY.md

OpenFDE

Local-first environment discovery and deployment preflight for Forward Deployed Engineers.

OpenFDE is an open-source delivery harness for engineers who enter unfamiliar customer environments, map what is really there, validate deployment constraints, and leave behind reusable operational knowledge instead of another one-off implementation.

The long-term goal is simple:

Make Forward Deployed Engineering repeatable, inspectable, and portable across customer engagements.

OpenFDE is not another AI agent framework, LLM gateway, observability backend, or project-management product. It is the lifecycle layer that sits around the tools you already use.

Why OpenFDE?

Forward Deployed Engineers repeatedly face the same class of problems:

• Every customer has a different cloud, auth model, network layout, data boundary, and deployment process.
• Important constraints live in Slack threads, architecture calls, spreadsheets, and people's heads.
• AI prototypes often reach production without a consistent preflight for data, permissions, evals, reliability, or human approval.
• The same Salesforce/Slack/Postgres/S3 integration patterns are rebuilt from scratch.
• Handoffs lose the context behind architecture decisions and known failure modes.
• Knowledge from customer #1 rarely compounds into faster delivery for customer #10.

OpenFDE turns that repeated work into an executable workspace.

Customer Problem
      ↓
Discovery
      ↓
Environment
      ↓
Architecture
      ↓
Build
      ↓
Eval
      ↓
Deploy
      ↓
Operate
      ↓
Handoff
      ↓
Reusable Knowledge

V0.1: the useful wedge

The first release deliberately focuses on five commands:

fde init
fde scan
fde map
fde check
fde report

The goal is to make OpenFDE useful within five minutes of cloning an unfamiliar repository.

Example

git clone git@github.com:customer/support-platform.git
cd support-platform

fde init
fde scan
fde map
fde check
fde report

Expected output:

OpenFDE Scan

Detected 14 components

Runtime
  ✓ Node.js
  ✓ Python

Infrastructure
  ✓ Docker
  ✓ Terraform
  ✓ Kubernetes manifests

Data
  ✓ PostgreSQL
  ✓ Redis
  ✓ S3 references

AI
  ✓ OpenAI SDK

Observability
  ✓ Sentry
  ✓ OpenTelemetry

CI/CD
  ✓ GitHub Actions

Then:

OpenFDE Deployment Readiness

Security       72
Data           61
Reliability    84
Evaluation     42
Observability  91
Human Control  55

Overall        68 / 100

CRITICAL
- Production database write boundary is not declared.
- AI policy allows external model access but PII handling is undefined.

WARNING
- No regression evaluation suite declared.
- No model fallback policy detected.
- Human approval boundary is missing for a side-effecting workflow.

Core primitive: the FDE Engagement

OpenFDE treats an engagement as the primary unit of work.

Terraform models infrastructure state. Kubernetes models workload state. OpenFDE models the state and constraints of a customer deployment engagement.

A repository can declare an engagement using fde.yaml:

apiVersion: openfde.dev/v1alpha1
kind: Engagement
metadata:
  name: acme-ai-support

spec:
  customer:
    name: acme

  objective:
    summary: Automate first-line support resolution

  successMetrics:
    - name: resolution_rate
      target: ">= 0.70"
    - name: p95_response_time
      target: "< 30s"

  environment:
    cloud: aws
    regions:
      - ap-southeast-1

  systems:
    - id: crm
      type: salesforce
      access: read_write
    - id: primary_db
      type: postgres
      access: read_only
    - id: collaboration
      type: slack
      access: read_write

  constraints:
    dataResidency:
      allowedRegions:
        - ap-southeast-1
    pii:
      allowExternalModel: false
    humanApproval:
      requiredFor:
        - refund.execute
        - customer.delete

The schema is intentionally designed to be:

• machine-readable;
• source-controlled;
• local-first;
• vendor-neutral;
• extensible by plugins;
• understandable by humans and coding agents.

See schemas/fde.schema.json and docs/FDE_SCHEMA.md.

Workspace layout

OpenFDE stores engagement artifacts in .fde/.

.fde/
├── engagement.yaml
├── environment/
│   ├── inventory.json
│   ├── integration-graph.json
│   └── integration-graph.mmd
├── architecture/
│   └── decisions/
├── policies/
├── evals/
├── deployments/
├── traces/
├── incidents/
├── evidence/
├── runbooks/
├── handoff/
└── learnings/

V0.1 only uses a subset of this structure. The rest documents the direction of the project without forcing a large platform into the first release.

Command overview

fde init

Creates the engagement workspace and a starter fde.yaml.

fde init

Creates:

fde.yaml
.fde/
└── environment/

The first version keeps prompts minimal and safe for source control.

fde scan

Discovers technical signals from the local repository.

fde scan

Initial scanners look for:

• languages and runtimes;
• package managers;
• Docker;
• Kubernetes manifests;
• Terraform;
• GitHub Actions;
• common databases;
• common queues/caches;
• cloud SDK references;
• AI providers;
• observability tooling;
• auth/SSO signals.

Output:

.fde/environment/inventory.json

Local-first by default

fde scan must never upload source code, .env files, secrets, customer data, or inventory output unless a future integration is explicitly configured by the user.

fde map

Turns discovered components into a machine-readable integration graph plus Mermaid output.

fde map

Outputs:

.fde/environment/integration-graph.json
.fde/environment/integration-graph.mmd

Example edge:

{
  "from": "ai-agent",
  "to": "primary-db",
  "relationship": "queries",
  "access": "read_only",
  "data": ["customer_profile"],
  "containsPii": true
}

The graph becomes a common substrate for later policy checks, risk analysis, incident replay, agent permissions, and deployment evidence.

fde check

Runs deployment-readiness checks against repository discovery plus the declared engagement.

fde check

Initial check groups:

1. Security — secrets handling, privileged access declarations, dangerous write boundaries.
2. Data — PII handling, residency, external model policy.
3. Reliability — timeout/retry/fallback declarations.
4. Evaluation — regression/eval artifacts.
5. Observability — tracing/error monitoring signals.
6. Human Control — declared approval boundaries for side-effecting actions.

Checks should always explain why something was flagged and which evidence produced the result.

OpenFDE should prefer explainable checks over opaque AI scores.

fde report

Generates a shareable Markdown report from the current workspace.

fde report

Output:

.fde/report.md

The report includes:

• engagement summary;
• detected environment;
• deployment-readiness score;
• critical findings;
• warnings;
• open questions;
• architecture map location;
• suggested next actions.

This gives FDEs a concrete artifact they can review with a customer without requiring a hosted dashboard.

Design principles

1. Local-first

A Forward Deployed Engineer may be working inside highly restricted customer environments. OpenFDE should provide useful value without requiring a cloud account.

2. Vendor-neutral

OpenFDE should work around Terraform, Kubernetes, Sentry, OpenTelemetry, LangSmith, cloud providers, coding agents, and internal tooling rather than attempting to replace them.

3. Executable over documentation-only

Markdown templates can support the workflow, but the core value should come from executable discovery, validation, tests, and evidence generation.

4. Human-readable + machine-readable

Every important artifact should be understandable in Git while remaining structured enough for automation.

5. Evidence over magic scoring

Every warning or score should map back to observable evidence, declared configuration, or a clearly named heuristic.

6. Safe defaults

No automatic secret upload. No arbitrary production writes. No hidden network calls. Destructive operations should require explicit opt-in.

7. Existing tools stay in place

OpenFDE should orchestrate existing tools rather than rebuild mature infrastructure.

Architecture

                     FDE ENGINEER
                          │
                          ▼
                  ┌───────────────┐
                  │  OpenFDE CLI  │
                  └───────┬───────┘
                          │
                          ▼
             ┌────────────────────────┐
             │       FDE CORE         │
             │                        │
             │ Engagement             │
             │ Environment            │
             │ Integration Graph      │
             │ Constraints            │
             │ Checks                 │
             │ Evidence               │
             └────────────┬───────────┘
                          │
                    .fde workspace
                          │
             ┌────────────┼────────────┐
             ▼            ▼            ▼
          Scanners      Plugins      Policies
             │            │            │
             └────────────┼────────────┘
                          ▼
                 Existing Tooling
          Terraform / K8s / OTel / Sentry
                          │
                          ▼
                 Customer Production

For the detailed component model, see docs/ARCHITECTURE.md.

Proposed long-term lifecycle

OpenFDE may eventually cover six pillars:

01 DISCOVER   Customer environment
02 MODEL      Systems + relationships
03 GOVERN     Constraints + polici