suboss87/fde-os

# GitHub Repository: suboss87/fde-os

**URL:** https://github.com/suboss87/fde-os
**Author:** suboss87
**Description:** Second brain for Forward Deployed Engineers — one @fde skill, phase methods that do the work, self-writing engagement memory. Claude Code plugin.
**Homepage:** 
**Language:** JavaScript

## Stats
- Stars: 0
- Forks: 0
- Open Issues: 0
- Commits: 18
- Created: 2026-06-11T08:03:27Z
- Updated: 2026-06-18T16:24:47Z
- Pushed: 2026-06-18T16:24:40Z

## README
# FDEOS - The Operating System for Forward Deployed Engineers

> **One command. Six domains. Your second brain for client engagements.**

You type **`@fde`**, describe your situation, and the system routes to the right method - from first stakeholder meeting to final handoff. Every skill writes its output to your private engagement memory (`.fde/`), so tomorrow starts where today ended. No re-pasting context. No maintaining notes. No picking from a catalog.

```mermaid
flowchart LR
    A["@fde"] --> B{"Describe\nyour situation"}
    B --> C["Embed & Trust"]
    B --> D["Discover & Diagnose"]
    B --> E["Plan & Align"]
    B --> F["Build & Guard"]
    B --> G["Ship & Verify"]
    B --> H["Operate & Close"]
    C --> I[".fde/ memory\n(auto-written)"]
    D --> I
    E --> I
    F --> I
    G --> I
    H --> I
    I --> J["Next session\nloads automatically"]
```

Works with **Claude Code** · **Cursor** · **Copilot** · **Devin** · **Gemini CLI** · any agent that reads SKILL.md

<p align="center"><strong>The CLI (zero tokens, zero network)</strong></p>
<p align="center"><img src="media/terminal-demo.svg" alt="fde CLI - status, scan, dashboard" width="720"/></p>

<p align="center"><strong>The Fieldbook Dashboard (one offline HTML file)</strong></p>
<p align="center"><img src="media/fieldbook-dashboard.png" alt="FDE Fieldbook - portfolio view" width="720"/></p>

---

## Who does what

| 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) - **not** a human colleague | Loads the `@fde` skill, runs the phase methods, writes code and `.fde/` artifacts |
| **`@fde`** | **One skill** inside the AI agent | Hears your situation, routes to the right phase, does that phase's work |

**In this repo, "agent" always means the AI coding agent, never a person.**

---

## Without FDEOS vs with FDEOS

| | **Without FDEOS** | **With FDEOS** |
|---|-------------------|----------------|
| **Memory** | Re-paste context every session | `.fde/` writes itself - next session starts where today ended |
| **Discovery** | Agent treats the brief as the task | Agent scans churn, test gaps, "temporary" code; hands you the real problem with evidence |
| **Multiple customers** | Details blur between clients | One folder per customer, auto-loaded, never merged |
| **The output** | Advice you already knew | An artifact you carry into the sponsor meeting |

---

## Quickstart

```bash
# Option A: Skills CLI (any agent)
npx skills add suboss87/fde-os

# Option B: Clone + install
git clone https://github.com/suboss87/fde-os.git
cd fde-os && node bin/install.js
```

Start your first engagement:
```bash
node bin/install.js init my-client
# Memory lives at: ~/fde-engagements/my-client/.fde/
```

Point the AI coding agent at it:
```bash
export FDEOS_ENGAGEMENT=~/fde-engagements/my-client/.fde
```

Then talk to your agent:
```
@fde I'm on site. First stakeholder meeting tomorrow. Brief says fix the payments API.
```

That's it. The system takes over from there.

### Use it in any tool

One brain (`skills/fde/SKILL.md`), a thin pointer per tool. Wire up an engagement workspace for every AI tool you use:

```bash
node bin/install.js adapters ~/fde-engagements/my-client
# or: npx fdeos@latest adapters ~/fde-engagements/my-client
```

| Tool | Pointer file it reads |
|------|-----------------------|
| Claude Code | plugin + `~/.claude/FDEOS-CLAUDE.md` |
| Codex / OpenAI / generic | `AGENTS.md` |
| Gemini CLI | `GEMINI.md` |
| Cursor | `.cursor/rules/fde.mdc` |
| GitHub Copilot | `.github/copilot-instructions.md` |

Each file just points at `@fde` - so the method, overlays, and memory stay in one place. Details: [`adapters/`](adapters/README.md).

---

## How it works

```text
  YOU (human FDE)                    AI CODING AGENT (software)
  meetings, judgment        @fde      routes → right skill → does the work
        │                 ─────►      .fde/ memory (self-writing)
        │                                   │
        └──────────────►  client workspace (code, VPN, tickets)
```

| Layer | What | Where |
|-------|------|-------|
| **Surface** | One command: `@fde` | You type it |
| **Router** | Hears your situation, picks the skill | `SKILL.md` |
| **Skills** | 34 methods across 6 domains | `references/` |
| **Overlays** | Activate on signal (AI, fintech, healthcare, gov, artifacts) | Layer on top |
| **Memory** | `.fde/` - engagement record, per customer | Your machine |

---

## The basic workflow

You only ever type **`@fde`**. The AI coding agent reads `context.md` from your engagement folder, routes to the matching skill, and follows that skill's method:

1. **Describe** - tell the agent what's happening ("new client", "production is down", "need a board update")
2. **Route** - the system picks the right skill from 34 options across 6 domains
3. **Execute** - the skill's method runs, artifacts are written to `.fde/`, you review at checkpoints

---

## The 6 domains

### 1. Embed & Trust
*First days. Getting access, building credibility, understanding scope.*

| Skill | What it does |
|-------|-------------|
| **land** | First 48 hours: interrogate the brief, map stakeholders, define success before code |
| **audit** | Taking over mid-project: verify claims, find the load-bearing wall |
| **stakeholder-radar** | Map who decides, who blocks, who's about to escalate |
| **trust-engineering** | The trust ladder from observer to trusted; navigate AI policy |
| **scope-defense** | "Let me place it": scope receipts, the accumulation conversation |

### 2. Discover & Diagnose
*Finding the real problem. Testing what the brief claims.*

| Skill | What it does |
|-------|-------------|
| **discover** | Scan repo + hunt the workaround + **workshop facilitation** + **data estate assessment** |
| **assumption-audit** | Extract untested assumptions, classify by blast radius, kill the riskiest first |
| **use-case-scoring** | Score on value × urgency × alignment × data readiness ÷ complexity |
| **sketch** | Prototype the killer assumption in one day; kill fast, log the learning |

### 3. Plan & Align
*Sequencing work and getting sponsor alignment.*

| Skill | What it does |
|-------|-------------|
| **plan** | Work backwards from success + **estimation** (3-point sizing) + **migration strategy** |
| **business-case** | Cost of doing nothing → investment → return → sensitivity check |
| **options-analysis** | Three genuine options (conservative / pragmatic / ambitious) |
| **initiative-triage** | 20 things are "urgent"; pick 3 for Now, make trade-offs visible |

### 4. Build & Guard
*Safe implementation on someone else's codebase.*

| Skill | What it does |
|-------|-------------|
| **build** | Blast radius + legacy safety + **integration design** + **team amplification** |
| **incremental-build** | Vertical slices, 100–300 lines each, visible progress every 2–3 days |
| **test-on-legacy** | Characterise first, Strangler Fig, spot lying tests |
| **blast-radius** | Trace dependencies, classify impact (CONTAINED → IRREVERSIBLE) |
| **debug** | Systematic: reproduce → isolate → one hypothesis → verify |
| **rescue** | Production fire, trust fire, wrong-brief-mid-build, **or full pivot** |
| **security-audit** | Threat model in 5 minutes, STRIDE pass, secrets scan |
| **observability** | Define "working" before instrumenting; the four metrics |

### 5. Ship & Verify
*Getting to production without surprises.*

| Skill | What it does |
|-------|-------------|
| **ship** | Pre-flight + canary + rollback + **scale-readiness gate** + **progressive adoption** |
| **review** | Scope first (did we build what was agreed), then safety |
| **rollback-drill** | Test the escape route on staging before you need it at 2am |
| **qa-live** | Test from the user's chair, real browser, five perspectives |

### 6. Operate & Close
*Running the engagement and ending it well.*

| Skill | What it does |
|-------|-------------|
| **status** | Sponsor update from the week's actual record |
| **demo-prep** | The one number, live-vs-canned, five hard questions |
| **debrief** | Walk out of any meeting → decisions, signals, actions in memory |
| **exec-narrative** | Pyramid: governing thought, three supports, SCQA frame |
| **dashboard** | Portfolio view across all customers, trust-ordered |
| **multi-customer-ops** | Daily triage, context-switch, cross-contamination prevention |
| **close** | Retrospective, the 2am handoff document, what we learned |
| **handoff-engineering** | Operations runbook, knowledge transfer, confidence scoring |
| **pattern-extract** | If you did it twice, encode it; patterns are compound interest |

### Overlays (activate on signal)

| Overlay | Triggers on | What it adds |
|---------|------------|-------------|
| **ai** | AI, ML, LLM, model, embeddings, RAG, agents | Model selection, RAG architecture, agent safety, governance, drift monitoring, cost management |
| **artifacts** | deck, slides, report, governance, compliance | Executive decks, governance frameworks, ADRs, compliance packs, value reports |
| **fintech** | payments, PCI, banking, cardholder data | Idempotency, transaction integrity, fraud signals, silent-failure prevention |
| **healthcare** | PHI, HIPAA, patient data | De-identification, minimum-necessary, audit trails |
| **gov** | FedRAMP, ATO, CUI, classified | Authority boundaries, CUI marking, continuous monitoring |

---

## What makes FDEOS different

| Other skill repos | FDEOS |
|---|---|
| No client memory - re-paste every session | `.fde/` writes itself; next session loads automatically |
| No engagement politics - pure engineering | Skills for stakeholder radar, trust, scope defense, exec narratives |
| No multi-customer support | One folder per client, portfolio dashboard, hard isolation |
| Flat list of skills - find it yourself | Type `@fde`, describe the situation, it routes |
| Generic engineering or startup advice | FDE-specific: brownfield safety, earned access, sponsor alignment, workshop facilitation |
| No document generation | **Artifacts overlay:** governance frameworks, exec decks, compliance packs, ADRs from memory |
| No AI project guidance | **AI overlay:** model selection, RAG, agents, governance, drift, cost at scale |

---

## Engagement memory (`.fde/`)

Your **fieldbook** - one per client, private to you, plain markdown:

| File | Role | Written by |
|------|------|-----------|
| `context.md` | Where you are; loaded first every session | every phase + session-stop hook |
| `brief.md` | What they said - hypothesis until discover | land |
| `success.md` | Done, measured, signed-off by whom | land |
| `reality.md` | The real problem, with evidence | discover / audit |
| `terrain.md` | Codebase map: hotspots, test gaps, AI components, data estate | discover / audit |
| `stakeholders.md` | Champions, resistance, trust signals | land, updated continuously |
| `trust-profile.md` | Sacred data, AI policy, approval chain | land + overlays |
| `decisions.md` | Plan + choices + integration contracts + sizing | plan / build / review / rescue |
| `risks.md` | Live risk register | all phases |
| `delivery.md` | What shipped, business value, rollback, pulse, adoption metrics | build / ship |

Every claim carries evidence: `(ops lead, Day 5)` · `(churn: 47/90d)` · `(stated, unverified)`.

---

## The CLI (works without AI)

```bash
fde scan       # day-1 recon: hotspots × tests, "temporary" code, AI calls, secrets
fde resume     # initialize or resume an engagement
fde log        # write decisions, risks, delivery, contacts
fde receipts   # search memory with dates
fde capture    # session-end snapshot
fde status     # portfolio triage across all customers
fde dashboard  # render every engagement into one offline fieldbook.html (0 tokens)
```

---

## Who this is for

| You are… | FDEOS helps when… |
|----------|-------------------|
| **New to embed work** | You get a method per phase, not just encouragement |
| **Senior operator, solo on site** | The agent is your second brain: memory + grunt work |
| **Multi-client consultant** | One `.fde/` per customer, never cross-contaminated |
| **Running AI transformations** | AI overlay: model selection → RAG → agents → scale → governance |
| **Enterprise programme lead** | Estimation, migration strategy, scale-readiness, governance artifacts |

**Works with:** Claude Code, Cursor, Copilot, Windsurf, Cline, Devin, Gemini CLI - any agent that reads SKILL.md.

---

## What's inside

```
bin/fde.js              the CLI - deterministic core, works without AI:
                          fde scan · resume · log · receipts · capture · status · dashboard
skills/fde/
  SKILL.md              the router: voice, memory contract, 6-domain routing
  references/
    34 skill files      one method per file
    5 overlays          ai.md, artifacts.md, fintech.md, healthcare.md, gov.md
hooks/                  session-start, session-stop, pre-compact
templates/.fde/         the 10 core memory files an init creates
docs/                   install guides, schema, methodology
```

---

## Principles

- **The artifact is the memory** - producing work and recording it are one action
- **Trust before production** - earn the right to touch their systems
- **Brief is a hypothesis** - discover before building the wrong thing
- **Evidence on every claim** - these files get defended in front of skeptical clients
- **Map before moving** - unknown terrain gets characterisation tests
- **Thin slices** - ship learning, not theatre
- **One customer, one folder** - context never bleeds
- **AI degrades silently** - monitor outputs, not just uptime
- **Scale readiness is organizational** - not just technical

---

## Updating

```bash
cd fde-os && git pull && node bin/install.js
```

---

## Contributing

Maintained by **Subash Natarajan**. Feedback via [Issues](https://github.com/suboss87/fde-os/issues) - see [CONTRIBUTING.md](CONTRIBUTING.md).

[ATTRIBUTION.md](ATTRIBUTION.md) · [SECURITY.md](SECURITY.md) · [Repo layout](docs/REPO_LAYOUT.md) · MIT