The layer between your AI coding agent and the client.
Your execution workflow skills teach the agent to ship code. FDEOS teaches it to survive the engagement — wrong briefs, quiet sponsors, shadow spreadsheets, trust crises, and the politics that kill projects before the code does.
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.
Built across years of embed work — enterprise, startup, regulated, rescue — mostly solo on site. Open source so you do not relearn the same political and delivery mistakes.
Day 5 of an engagement. The brief said "fix the payments API." You just left a meeting where finance mentioned a spreadsheet they reprocess every night. You open your AI chat:
You: @fde Workshop done. Ops says engineers fix API but finance still
reprocesses EU rows in Excel every night.
Agent: That spreadsheet is the real spec — not the API errors. The brief
was wrong. The actual problem is an ingest pipeline that fails
silently on EU-formatted amounts, and finance has been patching
it manually since 2023.
I've updated reality.md: the fix isn't the API returning 500 —
it's the silent parse failure upstream. success.md needs rewriting:
done = automated ingest with audit trail, not "API returns 200."
Before you touch code: who owns that spreadsheet? That person is
your real requirements source. Get 30 minutes with them tomorrow.
You: Also — the CTO hasn't responded to my last two messages.
Agent: That's a trust signal, not a scheduling issue. A sponsor who goes
quiet is not losing interest — they're escalating above you.
You have roughly 48 hours before someone you haven't met makes a
decision about this engagement.
Don't push harder on delivery. Set up a short call — curious, not
defensive. Ask what changed in their expectations. I've flagged
this in risks.md and updated context.md.
The AI didn't jump into code. It caught a wrong brief, identified the real problem, and flagged a trust crisis — because FDEOS skills teach engagement judgment, not just engineering.
| 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)
FDEOS is not another plan/build/review/ship skills pack. If you already use execution workflow skills for coding discipline, FDEOS adds the layer they don't cover:
| Execution workflow skills handle | FDEOS adds |
|---|---|
| Canary deploys, rollback procedures | Change advisory board awareness, programme-level rollout, customer notification |
| Reproduce → isolate → fix | Customer communication during debugging, chaos-log for handoff, escalation timing |
| Code correctness, edge cases | Scope-drift detection against decisions.md, trust-profile compliance, AI policy sign-off |
| Characterization tests, refactoring patterns | Refactoring classification as trust risk, three-option architecture for client buy-in |
Use both. Execution skills make your agent a disciplined engineer. FDEOS makes it a disciplined embedded operator.
| 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 |
| Taking over mid-engagement | @fde-audit separates what's real from what was assumed before you |
Requirements: An AI coding agent that loads custom instructions — Claude Code, Cursor, Windsurf, Codex, or anything that reads markdown skills/rules.
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 |
| Customer trust | Your problem alone | AI helps you detect trust signals and scope drift |
FDEOS does not get you access, approvals, or compliance sign-off. It structures how you (human) and your AI coding agent run the embed.
- Clone:
git clone https://github.com/suboss87/fde-os.git && cd fde-os - Install skills to your AI tool (setup by tool below)
- Init an engagement:
node bin/install.js init my-engagement - Set
FDEOS_ENGAGEMENT=~/fde-engagements/my-engagement/.fde - In the AI chat, type:
@fde I'm on site. First stakeholder meeting tomorrow. Brief says fix the payments API.
Works with Claude Code, Cursor, Windsurf, Codex, and any tool that loads markdown instructions. Setup by tool →
Deeper paths: docs/install.md · Example arcs: examples/
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 (e.g. ~/.claude/skills/, ~/.cursor/skills/, or your tool's rules path) |
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 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. Client-site implementation with scope discipline and trust-profile compliance.
-
review — Before merge. Scope alignment against
decisions.md, then safety (@fde-review). -
ship — Production. Change advisory boards, customer notification, programme-level rollout (
@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) |
Example arcs: examples/acme-payments/ · examples/healthco-migration/ · examples/finserv-rescue/
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— Client-site implementation: scope discipline, architecture options, trust-profile compliance@fde-review— Scope alignment againstdecisions.md, AI policy, trust-profile checks@fde-debug— Customer communication under pressure, chaos-log for handoff@fde-ship— Change advisory boards, programme rollout, pulse definitions
@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 |
trust-profile.md |
Sacred data, AI policy, approval chain |
risks.md |
Live risk register |
Do not commit client-identifying content to shared git.
Schema: docs/schema.md · Day-to-day: docs/USAGE.md
FDEOS skills are plain markdown. Any AI coding tool that reads custom instructions can use them. Pick your tool below.
git clone https://github.com/suboss87/fde-os.git
cd fde-os && node bin/install.jsThis copies skills to ~/.claude/skills/ and hooks to ~/.claude/hooks/. The session-start hook auto-loads @fde + your engagement context every session. The pre-compact hook preserves state before context compaction.
git clone https://github.com/suboss87/fde-os.git
cp -r fde-os/skills/* ~/.cursor/skills/Or add to your project's .cursor/rules file:
Load skills from ~/.cursor/skills/fde/SKILL.md on every session.
When I say @fde, follow the instructions in that skill.
Read context from the path in FDEOS_ENGAGEMENT environment variable.
git clone https://github.com/suboss87/fde-os.git
cp -r fde-os/skills/* ~/.windsurf/skills/Or reference the skills path in your Windsurf rules/cascade configuration.
Add the contents of skills/fde/SKILL.md as your project's system instructions. Point it at your .fde/ folder:
FDEOS_ENGAGEMENT=~/fde-engagements/<engagement-name>/.fde
Codex doesn't have hooks, so you'll manually ensure context loads — but the skills work the same way once loaded.
If your tool reads markdown instructions (rules files, system prompts, custom instructions), copy skills/fde/SKILL.md into wherever it loads from. The AI needs:
- The
@fdeskill loaded as instructions - Access to read/write files at
~/fde-engagements/<name>/.fde/ - The
FDEOS_ENGAGEMENTenv var pointing to the active engagement
That's it. No runtime, no server, no dependencies beyond the markdown files.
cd fde-os && node bin/install.js init <engagement-name>Set the env var so your AI knows which engagement to load:
FDEOS_ENGAGEMENT=~/fde-engagements/<engagement-name>/.fde
Full matrix: docs/install.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
- Complement, don't compete — Use FDEOS for the client layer; use your workflow skills for the code layer
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