From 7b6215b47115064952aefe0f68cdb4fbd75d1f22 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 27 Aug 2026 04:11:05 +0000 Subject: [PATCH] docs: the front door leads with the recorded session and states what works where Co-Authored-By: Subash Natarajan --- README.md | 152 +++++++++++++++++++++++++-------------------- adapters/README.md | 2 +- 2 files changed, 87 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index d81a610..0d10809 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,15 @@ # FDEOps -**Your AI coding agent forgets your client every morning. fdeops remembers.** +**Your AI coding agent forgets your client every morning. FDEOps remembers.** [![npm version](https://img.shields.io/npm/v/fdeops.svg)](https://www.npmjs.com/package/fdeops) [![CI](https://github.com/suboss87/fdeops/actions/workflows/validate.yml/badge.svg)](https://github.com/suboss87/fdeops/actions) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org) -**Memory + methodology + skills, in one kit.** Skill packs - BMAD, Spec-Kit, [mattpocock/skills](https://github.com/mattpocock/skills) - teach your AI coding agent how to *build*. None of them remember who the client is, what you promised them, or who agreed it was delivered. FDEOps adds the missing layer: a private fieldbook per engagement (`.fde/`), a field methodology (land → close), and one `@fde` skill that routes it all. +Skill packs teach your AI coding agent how to *build*. None of them remember who the client is, what you promised, or who agreed it was delivered. FDEOps adds that layer: a private fieldbook per engagement (`.fde/`), a field methodology from land to close, and one `@fde` skill that routes it. -Built for Forward Deployed Engineers, and anyone embedded in client work: consultants, agency developers, solutions architects, fractional CTOs. Feels like a second brain; behaves like a defensible record (dated, sourced, yours). +Built for Forward Deployed Engineers and anyone embedded in client work - consultants, agency developers, solutions architects, fractional CTOs. Feels like a second brain; behaves like a defensible record: dated, sourced, on your laptop. ``` land discover plan build ship close @@ -19,30 +19,21 @@ Built for Forward Deployed Engineers, and anyone embedded in client work: consul written as a side effect of the work ``` -Talk in plain language with `@fde`. The AI coding agent runs the plumbing. You confirm anything that enters the record. - --- -## The week +## A real session -`@fde` plus English. No cheat sheet. +Kickoff notes go in messy. You confirm what enters the record. A cold session the next morning already knows the client, the sponsor brief is grounded in dated facts, and the receipts survive the argument. Real CLI output - only the typing pace is staged, and you can [re-record it yourself](media/record-session.sh). -| When | What you say | What you get | -|------|--------------|--------------| -| **Start of week** | `@fde` — or just open Claude Code | Fieldbook on disk either way. **Claude Code** injects trust, phase, next before you type. **Cursor / Codex / others:** say `@fde` or `resume` — nothing auto-loads. | -| **After a meeting** | `@fde` debrief these notes *(paste or attach)* | Proposed updates. You review, then confirm. | -| **Optional: pull** | `@fde` connect Granola *(once)* · `@fde` pull today's Acme transcript | You add that source MCP. We **pull** on request — no push, no sync. [mcp/recipes/](mcp/recipes/) | -| **Before a stakeholder meeting** | `@fde` prep me for tomorrow with the sponsor | Brief from what you already logged. | -| **Scope dispute** | `@fde` when did we agree to drop that? | Dated answers, or a clear gap. | -| **End of week** | `@fde` draft the sponsor update from the record | Status grounded in what happened. | +

A real fdeops session: messy kickoff notes routed into dated memory after you confirm, then a cold session that already knows the client, a grounded sponsor-meeting brief, and dated receipts

-Same folder every time: `~/fde-engagements//.fde/`. +Nothing to install to see it on a fake client: `npx fdeops demo`. --- ## Quickstart -**1. Install.** Claude Code: session hooks (context before you type). Everywhere else: the same fieldbook, loaded when you ask. +**1. Install** on your machine - never in the customer's repo. ```text /plugin marketplace add suboss87/fdeops @@ -53,6 +44,8 @@ Same folder every time: `~/fde-engagements//.fde/`. npx skills add suboss87/fdeops # Cursor, Codex, skills-compatible hosts ``` +Claude Code additionally gets session hooks, so context arrives before you type. Everywhere else it is the same fieldbook, loaded when you ask. + **2. Bind once** in the client workspace: ```bash @@ -60,46 +53,74 @@ npx fdeops resume --init garvey # ~/fde-engagements/garvey + bind this checkou npx fdeops resume # where we are ``` -**3. Work** +**3. Work** in plain language: ```text @fde New client. Payments platform. They want it live before the Q3 audit. ``` -`@fde` routes and drafts; you confirm judgment. Workflow: [docs/USAGE.md](docs/USAGE.md). - -Working: `npx fdeops resume` prints this client's phase, trust, and next action. Tomorrow that file is still there. Auto-load at session start is Claude Code; elsewhere you invoke `@fde`. +**It is working if** `npx fdeops resume` prints this client's phase, trust signal, and next action - and prints the same thing tomorrow, from a new session, with no explaining. Full workflow: [docs/USAGE.md](docs/USAGE.md).
Other install paths · scan · env -- **Adapters:** `npx fdeops adapters .` — [adapters/](adapters/README.md) -- **Local LLMs:** load `skills/fde/SKILL.md` — [guide](adapters/LOCAL-LLM.md) +- **Adapters:** `npx fdeops adapters .` - [adapters/](adapters/README.md) +- **Local LLMs:** load `skills/fde/SKILL.md` - [guide](adapters/LOCAL-LLM.md) - **Air-gapped:** `git clone https://github.com/suboss87/fdeops.git && cd fdeops && node bin/install.js` - **No install:** `npx fdeops demo` · `npx fdeops scan` (heuristic recon, not findings) - **Requires:** Node.js >= 18 -- **Override:** `FDEOPS_ENGAGEMENT` — [docs/install.md](docs/install.md) +- **Override:** `FDEOPS_ENGAGEMENT` - [docs/install.md](docs/install.md)
--- +## The week + +`@fde` plus English. No cheat sheet. + +| When | What you say | What you get | +|------|--------------|--------------| +| **Start of week** | `@fde` - or just open Claude Code | Fieldbook on disk either way. **Claude Code** injects trust, phase, next before you type. **Cursor / Codex / others:** say `@fde` or `resume` - nothing auto-loads. | +| **After a meeting** | `@fde` debrief these notes *(paste or attach)* | Proposed updates. You review, then confirm. | +| **Optional: pull** | `@fde` connect Granola *(once)* · `@fde` pull today's Acme transcript | You add that source MCP. We **pull** on request - no push, no sync. [mcp/recipes/](mcp/recipes/) | +| **Before a stakeholder meeting** | `@fde` prep me for tomorrow with the sponsor | Brief from what you already logged. | +| **Scope dispute** | `@fde` when did we agree to drop that? | Dated answers, or a clear gap. | +| **End of week** | `@fde` draft the sponsor update from the record | Status grounded in what happened. | + +Same folder every time: `~/fde-engagements//.fde/`. + +--- + ## How it works -- **You** describe the situation with `@fde` (or plain language once the skill is loaded). -- **Hooks (Claude Code)** load where you left off and snapshot on the way out. Other hosts: same CLI and files; you call `@fde` / `resume`. -- **Local CLI** — writes, receipts, status. Zero model tokens. The AI coding agent runs it; you do not live in the CLI. [docs/USAGE.md](docs/USAGE.md) -- **Pull (optional)** — FDEOps is the sink. Paste is the daily path. A source MCP you add (Granola, Slack, Notion, …) can fetch text; `@fde connect …` walks config. No push, no sync, no tokens in `.fde/`. [mcp/recipes/](mcp/recipes/) +- **You** describe the situation with `@fde`, in plain language. +- **The AI coding agent** routes to a method, does the work, and drafts the memory. +- **The CLI** (`bin/fde.js`) does every write, receipt, and status check - git and file reads only, no network, no model tokens. You do not live in the CLI; your agent runs it. [docs/USAGE.md](docs/USAGE.md) +- **You confirm.** Nothing enters the record unreviewed; `fde debrief --dry-run` shows the routing first. + +`CLAUDE.md` is how the *code* works. The fieldbook is how the *engagement* works. It lives at `~/fde-engagements//.fde/`, not inside any vendor - change hosts, install `@fde` on the new one, keep talking. + +### What works where + +Honest boundaries, so nothing here needs a footnote: -`CLAUDE.md` is how the *code* works. The fieldbook is how the *engagement* works. The record lives at `~/fde-engagements//.fde/` — not inside any vendor. Change hosts, install `@fde` on the new one, bind if needed, keep talking. +| | Claude Code | Cursor · Codex · Copilot · Gemini · local LLMs | +|---|---|---| +| Fieldbook, methods, CLI, dashboard | yes | yes | +| Context loaded before you type | session hooks | you say `@fde` / `resume` | +| Snapshot on session end | session hooks | `@fde` capture, or `fde capture` | +| Pull from Granola / Slack / Notion | you add that source MCP; FDEOps only ingests | same | + +FDEOps is the sink, never the source: no push, no sync, no third-party tokens in `.fde/`. [mcp/recipes/](mcp/recipes/)
Phase verbs (land → close) | Verb | When | |------|------| -| **land** | First days — brief, stakeholders, success | -| **discover** | The brief is wrong — evidence from the repo | +| **land** | First days - brief, stakeholders, success | +| **discover** | The brief is wrong - evidence from the repo | | **plan** | Sequence backwards from done, PR-sized | | **build** | Blast radius, log what shipped | | **ship** | Pre-flight, canary, rollback | @@ -111,12 +132,29 @@ Overlays (AI, fintech, healthcare, gov) fire on signal. [docs/skills.md](docs/sk --- +## Engagement memory (`.fde/`) + +One folder per client. Plain markdown, so you can grep it, diff it, copy it into a readout, and defend it in a room. + +| File | Holds | +|------|-------| +| `context.md` | Where you are | +| `brief.md` / `success.md` | What they asked; what "done" is and who signs | +| `reality.md` / `terrain.md` | The real problem; the map | +| `stakeholders.md` | `[signal:green\|amber\|red]` | +| `trust-profile.md` | Sacred data, AI policy, approval chain | +| `decisions.md` / `risks.md` / `delivery.md` | Dated choices; live risks; what shipped and how it rolls back | + +A day-one fieldbook ships **empty** - headings and allowed values, no invented rows - so anything you read in it is something that actually happened. Schema: [docs/schema.md](docs/schema.md). + +--- + ## The field methods -You never pick one. You describe the situation; `@fde` routes. **37 methods**, six domains — each a method (thinking, artifact, checkpoint), not a tip sheet. [docs/skills.md](docs/skills.md) · [docs/skills-reference.md](docs/skills-reference.md) +You never pick one. You describe the situation and `@fde` routes. **37 methods** across six domains, each a method - thinking, artifact, checkpoint - not a tip sheet. [docs/skills.md](docs/skills.md) · [docs/skills-reference.md](docs/skills-reference.md)
-All 37 Skills +All 37 methods | Domain | Methods | |--------|---------| @@ -133,28 +171,11 @@ Overlays: [ai](skills/fde/references/ai.md) · [artifacts](skills/fde/references --- -## Engagement memory (`.fde/`) - -One folder per client. Plain markdown. Grep it, copy it, defend it. - -| File | Holds | -|------|-------| -| `context.md` | Where you are | -| `brief.md` / `success.md` | What they asked; what “done” is and who signs | -| `reality.md` / `terrain.md` | The real problem; the map | -| `stakeholders.md` | `[signal:green\|amber\|red]` | -| `trust-profile.md` | Sacred data, AI policy, approval chain | -| `decisions.md` / `risks.md` / `delivery.md` | Dated choices; live risks; what shipped and how it rolls back | - -Schema: [docs/schema.md](docs/schema.md). - ---- - ## Fieldbook UI -Local HTML: trust, phase, next, the record. `@fde` dashboard, or `npx fdeops dashboard` (`--all` for the portfolio). +`@fde` dashboard, or `npx fdeops dashboard` (`--all` for the portfolio): one local HTML file - trust, phase, next action, and the record behind them. Generated on demand, no server. -

fdeops Fieldbook in the browser

+

The fdeops Fieldbook dashboard: engagements with trust signal, phase and next action

--- @@ -162,10 +183,10 @@ Local HTML: trust, phase, next, the record. `@fde` dashboard, or `npx fdeops das | You are | What this is | |---------|----------------| -| **Forward Deployed Engineer** | The job this was built for — first meeting through handoff | +| **Forward Deployed Engineer** | The job this was built for - first meeting through handoff | | **Consultant / contractor on site** | The engagement stops resetting every morning | | **Solutions architect** | Politics and architecture in the same record | -| **Agency, 3–5 clients** | One `.fde/` each — they stop blurring | +| **Agency, 3-5 clients** | One `.fde/` each - they stop blurring | | **Fractional CTO on client work** | System of record for the embed, and the billable trail | --- @@ -173,22 +194,21 @@ Local HTML: trust, phase, next, the record. `@fde` dashboard, or `npx fdeops das ## Your data stays yours - **Local only.** `git` + files. No network, no telemetry, no account. Air-gapped is fine. -- **Plain markdown.** No database. -- **No new data path.** The model sees client code only when you point the AI coding agent at it. `` is redacted from CLI, dashboard, and hooks — do not open raw private blocks with file tools. -- **Nothing unreviewed.** Draft → you confirm. `fde debrief --dry-run` shows routing first. -- **Know the sync surface.** `~/fde-engagements` is in `$HOME`. iCloud/Dropbox is an NDA incident waiting. `resume --init` warns. [PRIVACY.md](PRIVACY.md) before the first NDA. +- **Plain markdown.** No database, no lock-in, nothing to export. +- **No new data path.** The model sees client code only when you point the AI coding agent at it. `` blocks are redacted from CLI, dashboard, and hook output - do not open raw private blocks with file tools. +- **Know the sync surface.** `~/fde-engagements` lives in `$HOME`. iCloud or Dropbox is an NDA incident waiting; `resume --init` warns you. -[PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md) +[PRIVACY.md](PRIVACY.md) before the first NDA · [SECURITY.md](SECURITY.md) --- ## Principles -- **The artifact is the memory** — producing the work and recording it are one action -- **Methods, not autonomy** — the kit says what to check; judgment stays yours -- **Brief is a hypothesis** — discover before building the wrong thing -- **Evidence on every claim** — these files get defended in the room -- **One customer, one folder** — context never bleeds +- **The artifact is the memory** - producing the work and recording it are one action +- **Methods, not autonomy** - the kit says what to check; judgment stays yours +- **Brief is a hypothesis** - discover before building the wrong thing +- **Evidence on every claim** - these files get defended in the room +- **One customer, one folder** - context never bleeds --- @@ -202,8 +222,8 @@ Re-run the Quickstart install, or from a clone: `git pull && node bin/install.js **[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. [Issues](https://github.com/suboss87/fdeops/issues) · [CONTRIBUTING.md](CONTRIBUTING.md) -Thanks to builders whose craft sharpened the thinking, among them [Andrej Karpathy](https://karpathy.ai/)'s engineering guidelines and the [agentic engineering workflow](https://github.com/pawel-cell/micky-podcast-agentic-engineering) notes from David Ondrej / Michael Shimeles. FDEOps is handcrafted for field work; resemblance is craft, not a fork. +Thanks to builders whose craft sharpened the thinking, among them [Andrej Karpathy](https://karpathy.ai/)'s engineering guidelines and the [agentic engineering workflow](https://github.com/pawel-cell/micky-podcast-agentic-engineering) notes from David Ondrej / Michael Shimeles. -**What we won't build:** SaaS sync; Slack/Notion/Granola connectors or **push** inside the CLI; CRM as core; hardware capture; generic code-craft packs (TDD/review live elsewhere). You may **pull** via *your* MCP. The `fde` CLI stays local-only. +**What we won't build:** SaaS sync; Slack/Notion/Granola connectors or **push** inside the CLI; CRM as core; hardware capture; generic code-craft packs (TDD and review live elsewhere). You may **pull** via *your* MCP. The `fde` CLI stays local-only. [FDE Methodology](FDE-METHODOLOGY.md) · [SECURITY.md](SECURITY.md) · [PRIVACY.md](PRIVACY.md) · [Repo layout](docs/REPO_LAYOUT.md) · [Skills matrix](docs/skills.md) · MIT diff --git a/adapters/README.md b/adapters/README.md index ea52979..f6f1c40 100644 --- a/adapters/README.md +++ b/adapters/README.md @@ -2,7 +2,7 @@ **One brain, thin adapters.** fdeops has a single source of truth - the `@fde` skill at `skills/fde/SKILL.md` and the `fde` CLI. Each AI coding tool discovers it through a small pointer file in the place that tool already looks. No forked logic, no five copies to maintain - every adapter says the same thing: *route via `@fde`, read/write `.fde/` memory, talk like a peer, never touch what isn't yours.* -**Switching tools:** the fieldbook does not live in the agent. It lives at `~/fde-engagements//.fde/`. Point a new tool at a bound workspace, drop adapters (or install the skill/plugin for that tool), and the same client record opens. Auto session hooks are Claude Code–first; elsewhere load via `@fde` / `fde resume`. See [README § Switch coding agents](../README.md#switch-coding-agents-anytime). +**Switching tools:** the fieldbook does not live in the agent. It lives at `~/fde-engagements//.fde/`. Point a new tool at a bound workspace, drop adapters (or install the skill/plugin for that tool), and the same client record opens. Auto session hooks are Claude Code–first; elsewhere load via `@fde` / `fde resume`. See [README § What works where](../README.md#what-works-where). ## What goes where