fdeops 3.10.2 → 3.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,15 +1,15 @@
1
1
  # FDEOps
2
2
 
3
- **Your AI coding agent forgets your client every morning. fdeops remembers.**
3
+ **Your AI coding agent forgets your client every morning. FDEOps remembers.**
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/fdeops.svg)](https://www.npmjs.com/package/fdeops)
6
6
  [![CI](https://github.com/suboss87/fdeops/actions/workflows/validate.yml/badge.svg)](https://github.com/suboss87/fdeops/actions)
7
7
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
8
8
  [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
9
9
 
10
- **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.
10
+ 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.
11
11
 
12
- 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).
12
+ 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.
13
13
 
14
14
  ```
15
15
  land discover plan build ship close
@@ -19,46 +19,21 @@ Built for Forward Deployed Engineers, and anyone embedded in client work: consul
19
19
  written as a side effect of the work
20
20
  ```
21
21
 
22
- Talk in plain language with `@fde`. The AI coding agent runs the plumbing. You confirm anything that enters the record.
23
-
24
- ---
25
-
26
- ## The week
27
-
28
- `@fde` plus English. No cheat sheet.
29
-
30
- | When | What you say | What you get |
31
- |------|--------------|--------------|
32
- | **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. |
33
- | **After a meeting** | `@fde` debrief these notes *(paste or attach)* | Proposed updates. You review, then confirm. |
34
- | **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/) |
35
- | **Before a stakeholder meeting** | `@fde` prep me for tomorrow with the sponsor | Brief from what you already logged. |
36
- | **Scope dispute** | `@fde` when did we agree to drop that? | Dated answers, or a clear gap. |
37
- | **End of week** | `@fde` draft the sponsor update from the record | Status grounded in what happened. |
38
-
39
- Same folder every time: `~/fde-engagements/<client>/.fde/`.
40
-
41
22
  ---
42
23
 
43
- ## See it
24
+ ## A real session
44
25
 
45
- ```bash
46
- npx fdeops demo
47
- ```
48
-
49
- Real commands on a fake client: messy notes → you confirm → cold reload → prep → receipts → fieldbook page. Nothing of yours is read. Lives in `~/fde-engagements/.demo/`. Remove with `npx fdeops demo --clean`.
50
-
51
- One recorded session — kickoff notes, next morning, “when did we agree?” weeks later. CLI output; typing pace is staged. Re-record: [`media/record-session.sh`](media/record-session.sh).
26
+ 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).
52
27
 
53
28
  <p align="center"><img alt="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" src="media/session.gif" width="900" /></p>
54
29
 
55
- Two things a chat window cannot do: **nothing is written until you confirm**, and `<private>` lands sealed as `(private - redacted)` — never in `resume`, `prep`, `receipts`, or the dashboard.
30
+ Nothing to install to see it on a fake client: `npx fdeops demo`.
56
31
 
57
32
  ---
58
33
 
59
34
  ## Quickstart
60
35
 
61
- **1. Install.** Claude Code: session hooks (context before you type). Everywhere else: the same fieldbook, loaded when you ask.
36
+ **1. Install** on your machine - never in the customer's repo.
62
37
 
63
38
  ```text
64
39
  /plugin marketplace add suboss87/fdeops
@@ -69,6 +44,8 @@ Two things a chat window cannot do: **nothing is written until you confirm**, an
69
44
  npx skills add suboss87/fdeops # Cursor, Codex, skills-compatible hosts
70
45
  ```
71
46
 
47
+ Claude Code additionally gets session hooks, so context arrives before you type. Everywhere else it is the same fieldbook, loaded when you ask.
48
+
72
49
  **2. Bind once** in the client workspace:
73
50
 
74
51
  ```bash
@@ -76,46 +53,74 @@ npx fdeops resume --init garvey # ~/fde-engagements/garvey + bind this checkou
76
53
  npx fdeops resume # where we are
77
54
  ```
78
55
 
79
- **3. Work**
56
+ **3. Work** in plain language:
80
57
 
81
58
  ```text
82
59
  @fde New client. Payments platform. They want it live before the Q3 audit.
83
60
  ```
84
61
 
85
- `@fde` routes and drafts; you confirm judgment. Workflow: [docs/USAGE.md](docs/USAGE.md).
86
-
87
- 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`.
62
+ **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).
88
63
 
89
64
  <details>
90
65
  <summary>Other install paths · scan · env</summary>
91
66
 
92
- - **Adapters:** `npx fdeops adapters .` [adapters/](adapters/README.md)
93
- - **Local LLMs:** load `skills/fde/SKILL.md` [guide](adapters/LOCAL-LLM.md)
67
+ - **Adapters:** `npx fdeops adapters .` - [adapters/](adapters/README.md)
68
+ - **Local LLMs:** load `skills/fde/SKILL.md` - [guide](adapters/LOCAL-LLM.md)
94
69
  - **Air-gapped:** `git clone https://github.com/suboss87/fdeops.git && cd fdeops && node bin/install.js`
95
70
  - **No install:** `npx fdeops demo` · `npx fdeops scan` (heuristic recon, not findings)
96
71
  - **Requires:** Node.js >= 18
97
- - **Override:** `FDEOPS_ENGAGEMENT` [docs/install.md](docs/install.md)
72
+ - **Override:** `FDEOPS_ENGAGEMENT` - [docs/install.md](docs/install.md)
98
73
 
99
74
  </details>
100
75
 
101
76
  ---
102
77
 
78
+ ## The week
79
+
80
+ `@fde` plus English. No cheat sheet.
81
+
82
+ | When | What you say | What you get |
83
+ |------|--------------|--------------|
84
+ | **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. |
85
+ | **After a meeting** | `@fde` debrief these notes *(paste or attach)* | Proposed updates. You review, then confirm. |
86
+ | **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/) |
87
+ | **Before a stakeholder meeting** | `@fde` prep me for tomorrow with the sponsor | Brief from what you already logged. |
88
+ | **Scope dispute** | `@fde` when did we agree to drop that? | Dated answers, or a clear gap. |
89
+ | **End of week** | `@fde` draft the sponsor update from the record | Status grounded in what happened. |
90
+
91
+ Same folder every time: `~/fde-engagements/<client>/.fde/`.
92
+
93
+ ---
94
+
103
95
  ## How it works
104
96
 
105
- - **You** describe the situation with `@fde` (or plain language once the skill is loaded).
106
- - **Hooks (Claude Code)** load where you left off and snapshot on the way out. Other hosts: same CLI and files; you call `@fde` / `resume`.
107
- - **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)
108
- - **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/)
97
+ - **You** describe the situation with `@fde`, in plain language.
98
+ - **The AI coding agent** routes to a method, does the work, and drafts the memory.
99
+ - **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)
100
+ - **You confirm.** Nothing enters the record unreviewed; `fde debrief --dry-run` shows the routing first.
101
+
102
+ `CLAUDE.md` is how the *code* works. The fieldbook is how the *engagement* works. It lives at `~/fde-engagements/<client>/.fde/`, not inside any vendor - change hosts, install `@fde` on the new one, keep talking.
103
+
104
+ ### What works where
105
+
106
+ Honest boundaries, so nothing here needs a footnote:
109
107
 
110
- `CLAUDE.md` is how the *code* works. The fieldbook is how the *engagement* works. The record lives at `~/fde-engagements/<client>/.fde/` — not inside any vendor. Change hosts, install `@fde` on the new one, bind if needed, keep talking.
108
+ | | Claude Code | Cursor · Codex · Copilot · Gemini · local LLMs |
109
+ |---|---|---|
110
+ | Fieldbook, methods, CLI, dashboard | yes | yes |
111
+ | Context loaded before you type | session hooks | you say `@fde` / `resume` |
112
+ | Snapshot on session end | session hooks | `@fde` capture, or `fde capture` |
113
+ | Pull from Granola / Slack / Notion | you add that source MCP; FDEOps only ingests | same |
114
+
115
+ FDEOps is the sink, never the source: no push, no sync, no third-party tokens in `.fde/`. [mcp/recipes/](mcp/recipes/)
111
116
 
112
117
  <details>
113
118
  <summary>Phase verbs (land → close)</summary>
114
119
 
115
120
  | Verb | When |
116
121
  |------|------|
117
- | **land** | First days brief, stakeholders, success |
118
- | **discover** | The brief is wrong evidence from the repo |
122
+ | **land** | First days - brief, stakeholders, success |
123
+ | **discover** | The brief is wrong - evidence from the repo |
119
124
  | **plan** | Sequence backwards from done, PR-sized |
120
125
  | **build** | Blast radius, log what shipped |
121
126
  | **ship** | Pre-flight, canary, rollback |
@@ -127,9 +132,26 @@ Overlays (AI, fintech, healthcare, gov) fire on signal. [docs/skills.md](docs/sk
127
132
 
128
133
  ---
129
134
 
135
+ ## Engagement memory (`.fde/`)
136
+
137
+ One folder per client. Plain markdown, so you can grep it, diff it, copy it into a readout, and defend it in a room.
138
+
139
+ | File | Holds |
140
+ |------|-------|
141
+ | `context.md` | Where you are |
142
+ | `brief.md` / `success.md` | What they asked; what "done" is and who signs |
143
+ | `reality.md` / `terrain.md` | The real problem; the map |
144
+ | `stakeholders.md` | `[signal:green\|amber\|red]` |
145
+ | `trust-profile.md` | Sacred data, AI policy, approval chain |
146
+ | `decisions.md` / `risks.md` / `delivery.md` | Dated choices; live risks; what shipped and how it rolls back |
147
+
148
+ 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).
149
+
150
+ ---
151
+
130
152
  ## The field methods
131
153
 
132
- 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)
154
+ 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)
133
155
 
134
156
  <details>
135
157
  <summary>All 37 methods</summary>
@@ -149,28 +171,11 @@ Overlays: [ai](skills/fde/references/ai.md) · [artifacts](skills/fde/references
149
171
 
150
172
  ---
151
173
 
152
- ## Engagement memory (`.fde/`)
153
-
154
- One folder per client. Plain markdown. Grep it, copy it, defend it.
155
-
156
- | File | Holds |
157
- |------|-------|
158
- | `context.md` | Where you are |
159
- | `brief.md` / `success.md` | What they asked; what “done” is and who signs |
160
- | `reality.md` / `terrain.md` | The real problem; the map |
161
- | `stakeholders.md` | `[signal:green\|amber\|red]` |
162
- | `trust-profile.md` | Sacred data, AI policy, approval chain |
163
- | `decisions.md` / `risks.md` / `delivery.md` | Dated choices; live risks; what shipped and how it rolls back |
164
-
165
- Schema: [docs/schema.md](docs/schema.md).
166
-
167
- ---
168
-
169
174
  ## Fieldbook UI
170
175
 
171
- Local HTML: trust, phase, next, the record. `@fde` dashboard, or `npx fdeops dashboard` (`--all` for the portfolio).
176
+ `@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.
172
177
 
173
- <p align="center"><img width="1336" height="624" alt="fdeops Fieldbook in the browser" src="https://github.com/user-attachments/assets/5683614c-7730-4a3a-860d-185053a377eb" /></p>
178
+ <p align="center"><img width="1336" height="624" alt="The fdeops Fieldbook dashboard: engagements with trust signal, phase and next action" src="https://github.com/user-attachments/assets/5683614c-7730-4a3a-860d-185053a377eb" /></p>
174
179
 
175
180
  ---
176
181
 
@@ -178,10 +183,10 @@ Local HTML: trust, phase, next, the record. `@fde` dashboard, or `npx fdeops das
178
183
 
179
184
  | You are | What this is |
180
185
  |---------|----------------|
181
- | **Forward Deployed Engineer** | The job this was built for first meeting through handoff |
186
+ | **Forward Deployed Engineer** | The job this was built for - first meeting through handoff |
182
187
  | **Consultant / contractor on site** | The engagement stops resetting every morning |
183
188
  | **Solutions architect** | Politics and architecture in the same record |
184
- | **Agency, 35 clients** | One `.fde/` each they stop blurring |
189
+ | **Agency, 3-5 clients** | One `.fde/` each - they stop blurring |
185
190
  | **Fractional CTO on client work** | System of record for the embed, and the billable trail |
186
191
 
187
192
  ---
@@ -189,22 +194,21 @@ Local HTML: trust, phase, next, the record. `@fde` dashboard, or `npx fdeops das
189
194
  ## Your data stays yours
190
195
 
191
196
  - **Local only.** `git` + files. No network, no telemetry, no account. Air-gapped is fine.
192
- - **Plain markdown.** No database.
193
- - **No new data path.** The model sees client code only when you point the AI coding agent at it. `<private>` is redacted from CLI, dashboard, and hooks do not open raw private blocks with file tools.
194
- - **Nothing unreviewed.** Draft you confirm. `fde debrief --dry-run` shows routing first.
195
- - **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.
197
+ - **Plain markdown.** No database, no lock-in, nothing to export.
198
+ - **No new data path.** The model sees client code only when you point the AI coding agent at it. `<private>` blocks are redacted from CLI, dashboard, and hook output - do not open raw private blocks with file tools.
199
+ - **Know the sync surface.** `~/fde-engagements` lives in `$HOME`. iCloud or Dropbox is an NDA incident waiting; `resume --init` warns you.
196
200
 
197
- [PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
201
+ [PRIVACY.md](PRIVACY.md) before the first NDA · [SECURITY.md](SECURITY.md)
198
202
 
199
203
  ---
200
204
 
201
205
  ## Principles
202
206
 
203
- - **The artifact is the memory** producing the work and recording it are one action
204
- - **Methods, not autonomy** the kit says what to check; judgment stays yours
205
- - **Brief is a hypothesis** discover before building the wrong thing
206
- - **Evidence on every claim** these files get defended in the room
207
- - **One customer, one folder** context never bleeds
207
+ - **The artifact is the memory** - producing the work and recording it are one action
208
+ - **Methods, not autonomy** - the kit says what to check; judgment stays yours
209
+ - **Brief is a hypothesis** - discover before building the wrong thing
210
+ - **Evidence on every claim** - these files get defended in the room
211
+ - **One customer, one folder** - context never bleeds
208
212
 
209
213
  ---
210
214
 
@@ -218,8 +222,8 @@ Re-run the Quickstart install, or from a clone: `git pull && node bin/install.js
218
222
 
219
223
  **[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. [Issues](https://github.com/suboss87/fdeops/issues) · [CONTRIBUTING.md](CONTRIBUTING.md)
220
224
 
221
- 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.
225
+ 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.
222
226
 
223
- **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.
227
+ **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.
224
228
 
225
229
  [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
@@ -2,7 +2,7 @@
2
2
 
3
3
  **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.*
4
4
 
5
- **Switching tools:** the fieldbook does not live in the agent. It lives at `~/fde-engagements/<client>/.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).
5
+ **Switching tools:** the fieldbook does not live in the agent. It lives at `~/fde-engagements/<client>/.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).
6
6
 
7
7
  ## What goes where
8
8
 
package/bin/check.js CHANGED
@@ -221,17 +221,20 @@ const readme = read('README.md')
221
221
  if (readme.includes('demo.gif')) fail('README must not embed media/demo.gif (staged mock, not real CLI output)')
222
222
  else ok('README no staged demo gif')
223
223
 
224
- if (!readme.includes('media/session.gif')) {
225
- fail('README must embed media/session.gif (the recorded session is the front door)')
226
- } else if (!readme.includes('media/record-session.sh')) {
227
- fail('README must link media/record-session.sh next to the recording, so it can be re-recorded')
224
+ // The recording may live on the front door or one click in (docs/USAGE.md), but
225
+ // it must stay reachable and reproducible - an orphaned gif rots silently.
226
+ const recordingHosts = ['README.md', 'docs/USAGE.md'].filter(f => read(f).includes('media/session.gif'))
227
+ if (!recordingHosts.length) {
228
+ fail('media/session.gif must be embedded in README.md or docs/USAGE.md (the recorded session is the proof)')
229
+ } else if (!recordingHosts.some(f => read(f).includes('media/record-session.sh'))) {
230
+ fail('link media/record-session.sh next to the recording, so it can be re-recorded')
228
231
  } else {
229
232
  const gifPath = path.join(root, 'media', 'session.gif')
230
233
  const rec = path.join(root, 'media', 'record-session.sh')
231
234
  if (!fs.existsSync(gifPath) || fs.statSync(gifPath).size < 50000) fail('media/session.gif missing or too small')
232
235
  else if (!fs.existsSync(rec)) fail('media/record-session.sh missing - the recording must be reproducible')
233
236
  else if (!fs.existsSync(path.join(root, 'media', 'session.cast'))) fail('media/session.cast missing - keep the source recording next to the gif')
234
- else ok('README recorded session (gif + reproducible recorder + cast)')
237
+ else ok(`recorded session in ${recordingHosts.join(' + ')} (gif + reproducible recorder + cast)`)
235
238
  }
236
239
 
237
240
  // Every repo-relative README link and image must resolve, or the front door 404s.
@@ -461,7 +464,7 @@ if (!fs.existsSync(path.join(root, 'bin', 'fde.js'))) {
461
464
  .map(name => path.join('bin', 'lib', name)),
462
465
  ]
463
466
  const cliSource = cliFiles.map(read).join('\n')
464
- for (const sub of ['cmdScan', 'cmdResume', 'cmdLog', 'cmdDebrief', 'cmdIngest', 'cmdReceipts', 'cmdCapture', 'cmdStatus', 'cmdDashboard']) {
467
+ for (const sub of ['cmdScan', 'cmdResume', 'cmdLog', 'cmdDebrief', 'cmdIngest', 'cmdReceipts', 'cmdCapture', 'cmdStatus', 'cmdDashboard', 'cmdVault']) {
465
468
  if (!cliSource.includes(sub)) fail(`CLI sources missing ${sub}`)
466
469
  }
467
470
  if (!JSON.parse(read('package.json')).bin.fde) fail('package.json must expose the fde bin')