FDEOS is a complete client-engagement methodology for you—the human Forward Deployed Engineer on site—working with an AI coding agent (e.g. Claude Code). It is built from composable skills the AI loads plus .fde/ memory the AI reads and updates so each session starts where you left off—not from zero.
You (human) describe what is happening on the engagement. You type @fde in the AI’s chat. The AI routes to the right phase (land, discover, plan, build, rescue, close). You do not memorize skill names.
Built across 100+ embeds (enterprise, startup, regulated, rescue), mostly solo on site. Open source so you do not relearn the same political and delivery mistakes.
| Role | Who | What they do |
|---|---|---|
| You (the FDE) | Human on the engagement | Stakeholder meetings, calls, judgment, sign-off, typing @fde, owning what ships |
| AI coding agent | Software on your laptop (e.g. Claude Code, Cursor with skills) — not a human colleague | Loads FDEOS skills, reads/updates .fde/, drafts code and docs in your workspace |
@fde |
Skill inside the AI agent | Routes your message to the right engagement phase |
In this repo, “agent” always means the AI coding agent, never a person (not the client’s team, not a forward-deployed human peer).
YOU (human FDE) AI CODING AGENT (software)
meetings, judgment @fde skills + .fde/ memory
│ ─────► │
│ ▼
└──────────────► client workspace (code, VPN, tickets)
Give your AI coding agent FDEOS: Claude Code (primary). Any tool that loads ~/.claude/skills/ can use the same files.
- Install plugin + copy skills (below)
node bin/install.js init my-engagement(from repo clone)- Set
FDEOS_ENGAGEMENT=~/fde-engagements/my-engagement/.fde - Open your workspace (repo, VPN, tickets—whatever access you already have)
- In the AI chat, type:
@fde I'm on site. First stakeholder meeting tomorrow. Brief says fix the payments API.
Deeper paths: docs/install.md · Example arc: examples/acme-payments/
It starts when you open a session and message the AI coding agent about the engagement.
The AI does not treat the written brief as truth and jump into implementation. It loads context.md from your private engagement folder—where you left off. You say what changed today (meeting, outage, quiet sponsor, wrong scope). @fde tells the AI whether you are landing, discovering, planning, building, rescuing, or closing, and which skills and .fde/ files to use.
While you work together, the AI should update that folder: who matters in stakeholders.md, what is actually broken in reality.md, what you agreed in decisions.md, what shipped in delivery.md. Next morning you are not re-pasting context into a blank chat.
| Layer | Where it lives | Who touches it |
|---|---|---|
| Skills | Your machine: ~/.claude/skills/ |
AI loads them; you install once |
| Engagement notes | ~/fde-engagements/<name>/.fde/ |
AI reads/writes; you own the folder |
| Code & delivery | Client workspace you already use | You + AI; FDEOS never installs on client servers by default |
your laptop client work (your access)
┌────────────────────────┐ ┌────────────────────────┐
│ Human: you (FDE) │ │ Meetings, repo, prod │
│ AI: @fde + skills │ @fde │ │
│ ~/fde-engagements/… │ ───────► │ │
└────────────────────────┘ └────────────────────────┘
Entry skill: @fde (skills/fde/SKILL.md). Other skills are reached through it.
| You are… | FDEOS helps when… |
|---|---|
| New to embed work | You need a clear first week before you touch production |
| Senior operator, solo on site | Your AI coding agent is your only backup for judgment + memory + delivery between meetings |
| Multi-client consultant | You must keep each engagement’s context separate |
Requirements: An AI coding agent that loads skills (Claude Code is what I use daily — install).
Not for: Teams who only need generic coding help in one repo, with no client politics, memory, or embed lifecycle.
| Without FDEOS | With FDEOS | |
|---|---|---|
| AI’s role | Strong coder | Coder + engagement partner |
| Memory | You re-paste context every session | context.md + .fde/ trail the AI reloads |
| Brief | AI treats it as the task | AI treats it as hypothesis until discover |
| Routing | You pick tools and prompts | @fde picks phase and skills |
| Risk | Right code, wrong problem or wrong room | Aims at alignment before big builds |
FDEOS does not get you access, approvals, or compliance sign-off. It structures how you (human) and your AI coding agent run the embed.
Install FDEOS once per AI tool if you use more than one (e.g. Claude Code and another editor with skills).
FDEOS is on the fde-os marketplace:
/plugin marketplace add suboss87/fde-os
/plugin install fdeos@fdeos
Copy skills and hooks to disk (once per machine):
git clone https://github.com/suboss87/fde-os.git
cd fde-os && node bin/install.jsWhen npm shows 2.1.0+: npx fdeos@latest (registry may lag—git clone is always current).
Per engagement:
node bin/install.js init <engagement-name>Tell the AI where notes live — in ~/.claude/FDEOS-CLAUDE.md or your shell:
FDEOS_ENGAGEMENT=~/fde-engagements/<engagement-name>/.fde
Full matrix: docs/install.md
You only type @fde in the AI chat. The AI coding agent checks your situation and activates the matching skill.
-
land — Day one. Stakeholders, brief as hypothesis, success and trust before code.
-
discover — Reality ≠ brief. Shadow work, real problem, terrain in
reality.md/terrain.md. -
plan — Sequence the next slices. PR-sized tasks, risks, cadence in
decisions.md/risks.md. -
build — Agreed slice. Legacy-safe implementation, characterization where fragile.
-
review — Before merge. Scope first, then safety (
@fde-review). -
ship — Production. Pre-flight, canary, rollback (
@fde-ship). -
close — Handoff. What the client team runs without you (
handoff.md,patterns.md).
Also routes to
| When | Skill |
|---|---|
| Production broken or trust crisis | @fde-rescue |
| Taking over half-done work | @fde-audit |
| Prove direction before big build | @fde-sketch |
| Several clients at once | @fde-dashboard (one init per client) |
Sample filled files (fictional): examples/acme-payments/
Skills are instructions the AI coding agent loads. You invoke only @fde.
@fde— Hear the situation; route silently to the right phase
@fde-land— First 48 hours: trust, stakeholders, success criteria@fde-discover— Real problem vs brief; shadow work; map the codebase@fde-audit— Mid-engagement takeover@fde-rescue— Outage or sponsor/trust crisis@fde-sketch— Prototype to test direction@fde-close— Handoff and patterns
@fde-engineering— Build → cleanup → review → verify loop@fde-plan— Atomic tasks, stakeholder touchpoints@fde-build— Brownfield-safe implementation@fde-review— Scope first, then safety@fde-debug— Reproduce, isolate, fix@fde-ship— Deploy with rollback
@fde-dashboard— Status across~/fde-engagements/
healthcare-fde,fintech-fde,gov-fde— Extra judgment for PHI, payments, or government data (operational guardrails, not legal advice)
Full list: docs/skills-reference.md
Default: ~/fde-engagements/<name>/.fde/ via FDEOS_ENGAGEMENT. Private to you; the AI reads/writes; client infra does not host this by default.
| File | Role |
|---|---|
context.md |
Where you are; AI loads first every session |
brief.md |
What they said—hypothesis until discover |
reality.md |
What is actually true |
stakeholders.md |
Champions, resistance, trust signals |
decisions.md |
Plan and technical choices |
delivery.md |
What shipped |
Do not commit client-identifying content to shared git.
Schema: docs/schema.md · Day-to-day: docs/USAGE.md
- Trust before production — You earn the right to touch their systems
- Brief is a hypothesis — Discover before the AI builds the wrong thing
- Map before moving — Unknown terrain gets characterization, not drive-by refactors
- Thin slices — Ship learning, not theatre
- Evidence over claims — Verify before you or the AI say it is fixed or done
- Engagement memory — Write it down so the next session is not day one again
Full methodology: FDE-METHODOLOGY.md
cd fde-os && git pull && node bin/install.jsPlugin updates follow Claude Code marketplace refresh. Re-run init only for new engagements—existing ~/fde-engagements/ folders are preserved.
Maintained by Subash Natarajan. Feedback via Issues — see CONTRIBUTING.md.
ATTRIBUTION.md · SECURITY.md · Repo layout · MIT