fdeops 3.9.2 → 3.9.3
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 +94 -157
- package/package.json +1 -1
- package/skills/fde/SKILL.md +9 -17
package/README.md
CHANGED
|
@@ -1,219 +1,156 @@
|
|
|
1
|
-
#
|
|
1
|
+
# fdeops
|
|
2
2
|
|
|
3
3
|
**Your AI coding agent forgets your client every morning. fdeops remembers.**
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
[](https://github.com/suboss87/fdeops/actions)
|
|
7
|
-
[](LICENSE)
|
|
8
|
-
[](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.
|
|
5
|
+
Local-first engagement fieldbook for Forward Deployed Engineers — memory under `.fde/` + one `@fde` router. Not an OS. Not a coworker.
|
|
21
6
|
|
|
22
7
|
---
|
|
23
8
|
|
|
24
|
-
##
|
|
9
|
+
## How it works
|
|
25
10
|
|
|
26
|
-
|
|
11
|
+
### The week
|
|
27
12
|
|
|
28
|
-
|
|
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 |
|
|
29
20
|
|
|
30
|
-
|
|
21
|
+
Same engagement folder every time. Git versions `.fde/`. Your AI coding agent reads it on every session.
|
|
31
22
|
|
|
32
|
-
|
|
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)
|
|
33
41
|
|
|
34
|
-
|
|
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 |
|
|
42
|
+
</details>
|
|
41
43
|
|
|
42
44
|
---
|
|
43
45
|
|
|
44
46
|
## Quickstart
|
|
45
47
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
/plugin install fdeops@fdeops
|
|
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
|
|
51
52
|
```
|
|
52
53
|
|
|
53
|
-
|
|
54
|
+
Then work as usual — `@fde` routes; the CLI owns scan, memory, receipts.
|
|
55
|
+
|
|
56
|
+
**CLI-only path** (npm global):
|
|
54
57
|
|
|
55
58
|
```bash
|
|
56
|
-
|
|
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"
|
|
57
64
|
```
|
|
58
65
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
66
|
+
| Flag | When |
|
|
67
|
+
|------|------|
|
|
68
|
+
| `--global` | Install once for your user |
|
|
69
|
+
| `--here` | This engagement only |
|
|
70
|
+
| *(default)* | Project + user, Claude Code |
|
|
62
71
|
|
|
63
|
-
|
|
72
|
+
<details>
|
|
73
|
+
<summary>Cursor · uninstall · upgrades · path override</summary>
|
|
64
74
|
|
|
65
|
-
```
|
|
66
|
-
|
|
75
|
+
```bash
|
|
76
|
+
fdeops install --cursor --global # Cursor project rules
|
|
77
|
+
fdeops uninstall # remove installed copies
|
|
78
|
+
fdeops upgrade # pull latest from npm
|
|
67
79
|
```
|
|
68
80
|
|
|
69
|
-
|
|
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>
|
|
81
|
+
Multiple engagements: `export FDEOPS_ENGAGEMENT=~/fde-engagements/acme`
|
|
75
82
|
|
|
76
|
-
|
|
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)
|
|
83
|
+
Full install notes: [`docs/install.md`](docs/install.md)
|
|
82
84
|
|
|
83
85
|
</details>
|
|
84
86
|
|
|
85
87
|
---
|
|
86
88
|
|
|
87
|
-
##
|
|
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
|
|
89
|
+
## Engagement memory
|
|
95
90
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
## How it works
|
|
91
|
+
Everything lives under `.fde/` in the engagement folder:
|
|
99
92
|
|
|
100
|
-
|
|
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 |
|
|
93
|
+
| Path | What |
|
|
108
94
|
|------|------|
|
|
109
|
-
|
|
|
110
|
-
|
|
|
111
|
-
|
|
|
112
|
-
|
|
|
113
|
-
|
|
|
114
|
-
|
|
|
115
|
-
|
|
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).
|
|
117
|
-
|
|
118
|
-
Works with **Claude Code** - **Cursor** - **Copilot** - **Gemini CLI** - **Ollama** - **LM Studio** - any model that reads a markdown file.
|
|
119
|
-
|
|
120
|
-
---
|
|
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 |
|
|
121
102
|
|
|
122
|
-
|
|
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.
|
|
123
104
|
|
|
124
|
-
|
|
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).
|
|
105
|
+
Commit `.fde/` like code. That's the whole compounding loop.
|
|
136
106
|
|
|
137
107
|
---
|
|
138
108
|
|
|
139
|
-
##
|
|
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:
|
|
109
|
+
## Without fdeops vs with fdeops
|
|
166
110
|
|
|
167
|
-
|
|
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 |
|
|
168
117
|
|
|
169
118
|
---
|
|
170
119
|
|
|
171
120
|
## Who this is for
|
|
172
121
|
|
|
173
|
-
|
|
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 |
|
|
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.
|
|
180
123
|
|
|
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)
|
|
124
|
+
Not for: generic chatbots, multi-tenant SaaS dashboards, or "AI coworker" shells.
|
|
192
125
|
|
|
193
126
|
---
|
|
194
127
|
|
|
195
128
|
## Principles
|
|
196
129
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
- **Thin slices** - ship learning, not theatre
|
|
203
|
-
- **One customer, one folder** - context never bleeds
|
|
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
|
|
204
135
|
|
|
205
136
|
---
|
|
206
137
|
|
|
207
|
-
##
|
|
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 |
|
|
208
146
|
|
|
209
147
|
```bash
|
|
210
|
-
|
|
148
|
+
npm test
|
|
149
|
+
node bin/check.js
|
|
211
150
|
```
|
|
212
151
|
|
|
213
152
|
---
|
|
214
153
|
|
|
215
|
-
##
|
|
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).
|
|
154
|
+
## License
|
|
218
155
|
|
|
219
|
-
|
|
156
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fdeops",
|
|
3
|
-
"version": "3.9.
|
|
3
|
+
"version": "3.9.3",
|
|
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,27 +146,19 @@ 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
|
|
149
|
+
## Forward momentum — `Next:` after land / debrief / ship only
|
|
150
150
|
|
|
151
|
-
After
|
|
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.
|
|
152
152
|
|
|
153
|
-
**
|
|
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)
|
|
153
|
+
**Format:** `Next: <one concrete move>` — grounded in what you just wrote to `.fde/`.
|
|
157
154
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
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.` |
|
|
162
160
|
|
|
163
|
-
**
|
|
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?"
|
|
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.
|
|
170
162
|
|
|
171
163
|
## Routing - 6 domains
|
|
172
164
|
|