fdeops 3.9.3 → 3.9.4

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.
Files changed (3) hide show
  1. package/README.md +157 -94
  2. package/package.json +1 -1
  3. package/skills/fde/SKILL.md +17 -9
package/README.md CHANGED
@@ -1,156 +1,219 @@
1
- # fdeops
1
+ # FDEOps
2
2
 
3
3
  **Your AI coding agent forgets your client every morning. fdeops remembers.**
4
4
 
5
- Local-first engagement fieldbook for Forward Deployed Engineers — memory under `.fde/` + one `@fde` router. Not an OS. Not a coworker.
5
+ [![npm version](https://img.shields.io/npm/v/fdeops)](https://www.npmjs.com/package/fdeops)
6
+ [![CI](https://github.com/suboss87/fdeops/actions/workflows/validate.yml/badge.svg)](https://github.com/suboss87/fdeops/actions)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
8
+ [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
9
+
10
+ The **second brain for Forward Deployed Engineers** - engineers embedded at a client, from first meeting to final handoff. Works the same for consultants, agency developers, solutions architects, and fractional CTOs.
11
+
12
+ ```
13
+ land discover plan build ship close
14
+ | | | | | |
15
+ +-----------+-----------+---------+----------+---------+
16
+ the fieldbook (.fde/) - one per engagement
17
+ written as a side effect of the work
18
+ ```
19
+
20
+ Describe your situation - `@fde` routes to the right method and writes the matching `.fde/` artifact. Phase methods (land → close) live in the skill; the CLI owns scan, memory, and receipts. You still confirm judgment — the fieldbook does not maintain itself without you.
6
21
 
7
22
  ---
8
23
 
9
- ## How it works
24
+ ## The problem
10
25
 
11
- ### The week
26
+ Your AI agent's memory is scoped to a **repo**. Client work isn't: one engagement spans several repos, a dozen stakeholders, and decisions made in meetings your agent never saw. That context lives in rooms, chats, and hallway conversations - nothing writes it down where your tools can use it.
12
27
 
13
- | When | What you do |
14
- |------|-------------|
15
- | **Monday** | Open agent → TRIAGE loads (trust, phase, next) |
16
- | **After a meeting** | `fde debrief --smart notes.txt` → review → `--apply` |
17
- | **Before a walk-in** | `fde prep "Denise sync"` |
18
- | **Scope fight** | `fde receipts descope` (+ memory git hash) |
19
- | **Friday** | `fde status` → sponsor update from the real record |
28
+ fdeops adds the missing layer: memory scoped to the **client** - plain markdown at `~/fde-engagements/<client>/.fde/`, written as a side effect of doing the work. Local only, zero dependencies, no network, no telemetry.
20
29
 
21
- Same engagement folder every time. Git versions `.fde/`. Your AI coding agent reads it on every session.
30
+ A notes app stores what you type. fdeops loads the right client into your AI agent's context automatically and turns meetings into dated receipts you can defend - the difference is what happens without you opening it.
22
31
 
23
- <details>
24
- <summary><strong>All methods (land → close)</strong> — below the fold</summary>
25
-
26
- | Method | When |
27
- |--------|------|
28
- | `land` | First day — bind people, success, risks |
29
- | `discover` | Map systems before you change them |
30
- | `prep` | Start of week — week's focus from memory |
31
- | `status` | Mid-engagement health check |
32
- | `triage` | Something broke — decide in 60s |
33
- | `debrief` | End of week — compound into memory |
34
- | `garden` | Memory hygiene — archive stale / promote truth |
35
- | `doctor` | Is `.fde/` healthy? |
36
- | `ship` | Before the blast — challenge, then go |
37
- | `red-team` | Adversarial pass before ship |
38
- | `close` | Engagement ends — archive + handoff |
39
-
40
- Full method map: [`docs/skills.md`](docs/skills.md)
32
+ ## Without fdeops vs with fdeops
41
33
 
42
- </details>
34
+ | Moment | Without fdeops | With fdeops |
35
+ |---|---|---|
36
+ | **Monday morning** | Re-paste last week's context, re-explain the stakeholders | A hook loads the engagement at session start - the agent opens knowing the deadline and the open thread |
37
+ | **After a meeting** | Notes rot in a scratch file | `fde debrief` routes decisions, risks, deliveries, and contacts into the record, dated |
38
+ | **Scope dispute** | "Small" additions absorbed silently; no record when the sponsor asks | `fde receipts <term>` answers "when did we agree to that?" with dates |
39
+ | **Quiet stakeholder** | Noticed three weeks too late | `fde log contact --signal amber` the day it happens; `fde status` surfaces it |
40
+ | **Multiple clients** | Details blur across engagements | One folder per client; bind the workspace so writes cannot land on a name-alike checkout |
43
41
 
44
42
  ---
45
43
 
46
44
  ## Quickstart
47
45
 
48
- ```bash
49
- npx skills add suboss87/fdeops # @fde skill (any agent that supports skills)
50
- # or Claude: /plugin marketplace add suboss87/fdeops
51
- npx fdeops resume --init haulline # bind this workspace → ~/fde-engagements/haulline
52
- ```
46
+ **1. Install** (Claude Code)
53
47
 
54
- Then work as usual — `@fde` routes; the CLI owns scan, memory, receipts.
48
+ ```text
49
+ /plugin marketplace add suboss87/fdeops
50
+ /plugin install fdeops@fdeops
51
+ ```
55
52
 
56
- **CLI-only path** (npm global):
53
+ **2. Bind your client workspace** - run once, inside the workspace:
57
54
 
58
55
  ```bash
59
- npm install -g fdeops
60
- fdeops install --global
61
- mkdir -p ~/fde-engagements && cd ~/fde-engagements
62
- fdeops init acme
63
- cd acme && git init && git add . && git commit -m "init engagement"
56
+ npx fdeops resume --init garvey
64
57
  ```
65
58
 
66
- | Flag | When |
67
- |------|------|
68
- | `--global` | Install once for your user |
69
- | `--here` | This engagement only |
70
- | *(default)* | Project + user, Claude Code |
59
+ (`npx` needs nothing pre-installed. Want the bare `fde` command the rest of this README uses? `npm i -g fdeops` - the plugin install alone does not put `fde` on your PATH.)
71
60
 
72
- <details>
73
- <summary>Cursor · uninstall · upgrades · path override</summary>
61
+ fdeops' `--init` creates the engagement memory at `~/fde-engagements/garvey/.fde/` (plain markdown, private to your machine) and binds this workspace to it. The hooks read that binding - context auto-loads at session start, auto-captures at session end. That is the whole setup.
74
62
 
75
- ```bash
76
- fdeops install --cursor --global # Cursor project rules
77
- fdeops uninstall # remove installed copies
78
- fdeops upgrade # pull latest from npm
63
+ **3. Work**
64
+
65
+ ```text
66
+ @fde I just got the brief. New client, payments platform, they want it live before their Q3 audit.
79
67
  ```
80
68
 
81
- Multiple engagements: `export FDEOPS_ENGAGEMENT=~/fde-engagements/acme`
69
+ `@fde` is the one skill fdeops installs. Describe what's happening; it routes to the right field method and writes matching `.fde/` artifacts — you still confirm judgment. Full workflow: [docs/USAGE.md](docs/USAGE.md).
70
+
71
+ Not ready to install? `npx fdeops scan` runs on any repo you can read - day-1 recon (pure `git` + file reads, no config, no account) that maps hotspots, test gaps, and reverted attempts, and ends with the ASK ON DAY 1 questions the brief never mentions. The scan is heuristic by design - treat its output as leads to verify on day one, not findings.
72
+
73
+ <details>
74
+ <summary><strong>Other install paths</strong> - Cursor, Codex, Copilot, Gemini CLI, local LLMs, air-gapped</summary>
82
75
 
83
- Full install notes: [`docs/install.md`](docs/install.md)
76
+ - **Cursor / Codex / Copilot / Gemini CLI:** `npx fdeops adapters .` drops a thin pointer to the same `@fde` skill - [adapters/](adapters/README.md)
77
+ - **Local LLMs (Ollama, LM Studio, llama.cpp):** load `skills/fde/SKILL.md` as the system prompt - [guide](adapters/LOCAL-LLM.md)
78
+ - **Skills CLI:** `npx skills add suboss87/fdeops`
79
+ - **Manual / air-gapped:** `git clone https://github.com/suboss87/fdeops.git && cd fdeops && node bin/install.js`
80
+ - **Requires:** [Node.js](https://nodejs.org) >= 18 for the CLI and adapters; the Claude Code plugin install does not need Node separately.
81
+ - **Advanced:** the `FDEOPS_ENGAGEMENT` env var overrides the workspace registry - only for unusual setups. Full matrix: [docs/install.md](docs/install.md)
84
82
 
85
83
  </details>
86
84
 
87
85
  ---
88
86
 
89
- ## Engagement memory
87
+ ## The week
88
+
89
+ This is the actual habit — the high-frequency loop, not the full skill matrix:
90
+
91
+ - **Monday morning** - open your agent, context loads, you're not re-explaining anything
92
+ - **After a meeting** - `fde debrief` turns raw notes into dated decisions, risks, and signals
93
+ - **Mid-scope-fight** - `fde receipts <term>` answers "when did we agree to that?"
94
+ - **Friday** - `fde status` gives you the sponsor update from the week's actual record
90
95
 
91
- Everything lives under `.fde/` in the engagement folder:
96
+ ---
97
+
98
+ ## How it works
92
99
 
93
- | Path | What |
100
+ Two hooks and one router, on top of the fieldbook:
101
+
102
+ - **Session start** - a hook loads where you left off into your AI coding agent's context
103
+ - **Session end** - a hook captures what happened back into the fieldbook
104
+ - **After meetings** - `fde debrief notes.md` routes lines prefixed `decision:` / `risk:` / `delivery:` / `contact:` to the matching file, dated; everything else lands as a dated block in `context.md`
105
+ - **On top of the memory** - the `@fde` skill routes six phase verbs:
106
+
107
+ | Verb | When |
94
108
  |------|------|
95
- | `.fde/people.md` | Who matters, trust, notes |
96
- | `.fde/log.md` | Running notes (append-only) |
97
- | `.fde/context.md` | Stack, constraints, systems |
98
- | `.fde/signals.md` | Verified facts + open questions |
99
- | `.fde/decisions.md` | Choices and why |
100
- | `.fde/risks.md` | Risks and owners |
101
- | `.fde/meta.json` | Phase, checksums, lock |
109
+ | **land** | First days at a new client - interrogate the brief, map stakeholders, define success |
110
+ | **discover** | The brief feels wrong - find the real problem, with evidence from the repo |
111
+ | **plan** | Scope agreed - sequence it backwards from success, in PR-sized slices |
112
+ | **build** | Ready to write code - declare blast radius, log deliveries as you ship |
113
+ | **ship** | Going to production - pre-flight, canary, tested rollback |
114
+ | **close** | Engagement ending - handoff doc, retrospective, receipts that survive you |
102
115
 
103
- Writes are **bound** (engagement required), **locked** (one writer), **atomic**, and **refused** when they look like secrets. Corrupt or incomplete state fails closed — never "green" by accident.
116
+ Overlays for regulated domains (AI, fintech, healthcare, government) activate on signal. fdeops complements your agent's native repo memory: CLAUDE.md holds how the *code* works; the fieldbook holds how the *engagement* works. Full matrix: [docs/skills.md](docs/skills.md).
104
117
 
105
- Commit `.fde/` like code. That's the whole compounding loop.
118
+ Works with **Claude Code** - **Cursor** - **Copilot** - **Gemini CLI** - **Ollama** - **LM Studio** - any model that reads a markdown file.
106
119
 
107
120
  ---
108
121
 
109
- ## Without fdeops vs with fdeops
122
+ ## Engagement memory (`.fde/`)
110
123
 
111
- | Without | With |
112
- |---------|------|
113
- | Context dies when the chat ends | `@fde prep` resurfaces last week's risks |
114
- | "We're fine" until the blast | Trust + signals force the hard conversation |
115
- | Notes scatter across Notion/Slack | One local fieldbook, git-versioned |
116
- | Agent invents stakeholders | Bind-required writes — no engagement, no write |
124
+ The **fieldbook** - one folder per client, plain markdown you can read, grep, and take with you:
125
+
126
+ | File | Holds |
127
+ |------|-------|
128
+ | `context.md` | Where you are - loaded first every session |
129
+ | `brief.md` / `success.md` | What they asked for; what "done" means and who signs it off |
130
+ | `reality.md` / `terrain.md` | The real problem; the codebase map |
131
+ | `stakeholders.md` | Champions, resistance, `[signal:green\|amber\|red]` trust tokens |
132
+ | `trust-profile.md` | Sacred data, AI policy, approval chain |
133
+ | `decisions.md` / `risks.md` / `delivery.md` | Choices with dates; live risk register; what shipped and its rollback |
134
+
135
+ Every entry is dated and sourced, so you can defend it in front of skeptical stakeholders. Schema: [docs/schema.md](docs/schema.md).
136
+
137
+ ---
138
+
139
+ ## The CLI
140
+
141
+ Deterministic, offline, zero tokens - the skill adds judgment on top:
142
+
143
+ ```bash
144
+ fde scan # day-1 recon + ASK ON DAY 1 questions (works via npx)
145
+ fde resume # TRIAGE + load this workspace's engagement
146
+ fde resume --init <client> # THE setup step: create + bind + git-version .fde/
147
+ fde triage # TRIAGE only (session hooks / Cursor entry)
148
+ fde debrief notes.md # route prefixed meeting notes (also reads stdin)
149
+ fde debrief --smart notes.md # propose routing from messy notes → --apply to confirm
150
+ fde prep "Denise sync" # grounded walk-in brief from existing memory
151
+ fde doctor # lint: stale signals, unset phase, gaps
152
+ fde log decision "descope agreed with Kowalczyk"
153
+ fde log contact "Denise gone quiet" --signal amber
154
+ fde receipts <term> # dated search; no hit = a gap in the record, not proof of absence
155
+ fde status # current engagement triage (add --all for every client)
156
+ fde dashboard # current engagement fieldbook (add --all for every client)
157
+ ```
158
+
159
+ Optional: `export FDEOPS_ENGAGEMENTS_ROOT=~/path/to/engagements` to isolate init/status/dashboard from the default `~/fde-engagements`.
160
+
161
+ Each `.fde/` is a local git repo (no remote, no telemetry) — dated entries carry an author tag; every write commits so receipts are tamper-evident. Worst-of `[signal:...]` per stakeholder drives trust; signals older than 21 days show as stale.
162
+
163
+ <p align="center"><img src="media/terminal-demo.svg" alt="fde CLI - status, scan, dashboard" width="720"/></p>
164
+
165
+ `fde dashboard` (FieldBook) renders the **current** engagement by default. Pass `--all` for every client sorted by trust:
166
+
167
+ <p align="center"><img width="1336" height="624" alt="Screenshot 2026-07-08 at 12 45 07" src="https://github.com/user-attachments/assets/5683614c-7730-4a3a-860d-185053a377eb" /></p>
117
168
 
118
169
  ---
119
170
 
120
171
  ## Who this is for
121
172
 
122
- FDEs, solutions engineers, and anyone dropped into a customer codebase who has to earn trust, ship under ambiguity, and not lose the thread between Mondays.
173
+ | You are... | What fdeops does for you |
174
+ |----------|-------------------|
175
+ | **Forward Deployed Engineer** | The role this was built for - the full lifecycle, first meeting to final handoff |
176
+ | **Consultant or contractor at a client site** | Remembers the engagement so you stop re-explaining it |
177
+ | **Solutions architect / engineer** | Methods for the politics as well as the architecture |
178
+ | **Agency developer running 3-5 clients** | One `.fde/` per client - details stop blurring |
179
+ | **Fractional CTO doing client work** | The fieldbook is your second brain - and your audit trail for billable work |
123
180
 
124
- Not for: generic chatbots, multi-tenant SaaS dashboards, or "AI coworker" shells.
181
+ ---
182
+
183
+ ## Your data stays yours
184
+
185
+ - **Local only.** Pure `git` + file reads - no network calls, no telemetry, no account. Works air-gapped.
186
+ - **Plain markdown.** No database, no lock-in.
187
+ - **No new data path.** The AI sees client code only when *you* point your agent at it; `<private>`-tagged data never enters the model's context.
188
+ - **Nothing enters the record unreviewed.** The model drafts, you confirm (`fde debrief --dry-run` shows the routing first); the hooks record only git facts. Your fieldbook stays yours to defend.
189
+ - **Know your sync surface.** `~/fde-engagements` lives in your home directory - your backup and cloud-sync setup now covers client notes. `fde resume --init` warns if the folder sits in a synced path. Read [PRIVACY.md](PRIVACY.md) before your first NDA'd engagement.
190
+
191
+ Details: [PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
125
192
 
126
193
  ---
127
194
 
128
195
  ## Principles
129
196
 
130
- 1. **Local-first** — memory on your disk, not a vendor cloud
131
- 2. **Compounding** — debrief is the product; chat is disposable
132
- 3. **Refuse bad writes** — secrets, symlinks, unbound paths
133
- 4. **Honest status** — corrupt ≠ green; worst stakeholder trust wins
134
- 5. **Thin packaging** — one skill (`@fde`), many methods — not a skill tree
197
+ - **The artifact is the memory** - producing work and recording it are one action
198
+ - **Methods, not autonomy** - each skill tells you what to check; the judgment, the trust, and the consequences stay yours
199
+ - **Trust before production** - earn the right to touch their systems
200
+ - **Brief is a hypothesis** - discover before building the wrong thing
201
+ - **Evidence on every claim** - these files get defended in front of skeptical clients
202
+ - **Thin slices** - ship learning, not theatre
203
+ - **One customer, one folder** - context never bleeds
135
204
 
136
205
  ---
137
206
 
138
- ## Docs
139
-
140
- | Doc | |
141
- |-----|--|
142
- | [Install](docs/install.md) | Global, Cursor, upgrades |
143
- | [Usage](docs/USAGE.md) | Methods in depth |
144
- | [Skills](docs/skills.md) | `@fde` method reference |
145
- | [CHANGELOG](CHANGELOG.md) | What changed |
207
+ ## Updating
146
208
 
147
209
  ```bash
148
- npm test
149
- node bin/check.js
210
+ cd fdeops && git pull && node bin/install.js
150
211
  ```
151
212
 
152
213
  ---
153
214
 
154
- ## License
215
+ ## Contributing
216
+
217
+ Built and maintained by **[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. Share your feedback via [Issues](https://github.com/suboss87/fdeops/issues) - see [CONTRIBUTING.md](CONTRIBUTING.md).
155
218
 
156
- MIT
219
+ [FDE Methodology](FDE-METHODOLOGY.md) - [ATTRIBUTION.md](ATTRIBUTION.md) - [SECURITY.md](SECURITY.md) - [PRIVACY.md](PRIVACY.md) - [Repo layout](docs/REPO_LAYOUT.md) - [Skills matrix](docs/skills.md) - MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fdeops",
3
- "version": "3.9.3",
3
+ "version": "3.9.4",
4
4
  "description": "Field kit for engineers embedded in client work - a real CLI (recon, memory, portfolio), one @fde skill with field judgment on top, and hooks that make it automatic. Claude Code plugin and any agent that loads skills.",
5
5
  "bin": {
6
6
  "fdeops": "bin/install.js",
package/skills/fde/SKILL.md CHANGED
@@ -146,19 +146,27 @@ The FDE can nod (zero friction) or correct ("billing-service too"). This replace
146
146
 
147
147
  **Never:** fire multiple questions at once, probe where the answer doesn't change the work, repeat what's already in the artifacts, or slow down a confident FDE to prove you're being thorough. One well-placed observation beats five careful questions.
148
148
 
149
- ## Forward momentum — `Next:` after land / debrief / ship only
149
+ ## Forward momentum (after writing memory)
150
150
 
151
- After **land**, **debrief** (once applied), or **ship** (proceed verdict), end with **one** directed line that starts with `Next:`. Not a menu. Not after every minor log/signal edit.
151
+ After updating `.fde/` artifacts, suggest the ONE next move that accelerates the engagement - but only when the next step isn't already obvious to the FDE.
152
152
 
153
- **Format:** `Next: <one concrete move>` — grounded in what you just wrote to `.fde/`.
153
+ **Do this when:**
154
+ - The FDE just finished a phase and the natural next step saves them thinking time
155
+ - There's a dependency that unblocks faster if acted on now (access request, stakeholder conversation, spec generation)
156
+ - The engagement is at a decision point (plan needs approval, risk needs escalation)
154
157
 
155
- | Just finished | Example |
156
- |---------------|---------|
157
- | **land** (brief + success written) | `Next: run fde scan on the repo, or draft the access ask if you don't have clone yet.` |
158
- | **debrief --apply** | `Next: fde prep "Denise sync" before Thursday, or fde status if you're writing the sponsor note.` |
159
- | **ship** (pre-blast proceed) | `Next: set the pulse in delivery.md, or fde log contact if Denise hasn't seen the canary.` |
158
+ **Don't do this when:**
159
+ - The FDE is clearly in flow and already knows what's next
160
+ - You just finished a minor update (logging a risk, updating a signal)
161
+ - The next step is obvious from context (mid-build, next task in sequence)
160
162
 
161
- **Skip `Next:` when:** the FDE is already in flow, you only logged a risk/signal, or the next step is obvious from the sequence they're mid-way through.
163
+ **The format:** One line, directed, based on engagement state. Not a menu.
164
+
165
+ > "Updated. Terrain is mapped - ready to plan the slices, or does Denise need to see this first?"
166
+
167
+ > "Shipped and logged. Task 4 touches the billing module where that open risk sits. Worth addressing that before starting?"
168
+
169
+ > "Brief written. You don't have repo access yet - want me to draft the request or are you handling that?"
162
170
 
163
171
  ## Routing - 6 domains
164
172