fdeops 3.9.4 → 3.9.6
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 +79 -69
- package/adapters/cursor.fde.mdc +3 -2
- package/bin/check.js +30 -1
- package/hooks/session-start +6 -15
- package/package.json +1 -1
- package/skills/fde/SKILL.md +27 -15
- package/skills/fde/references/debrief.md +35 -20
package/README.md
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
[](LICENSE)
|
|
8
8
|
[](https://nodejs.org)
|
|
9
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.
|
|
10
|
+
One `@fde` skill over a local client notebook (the **fieldbook** under `.fde/`) - one folder per client. 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
11
|
|
|
12
12
|
```
|
|
13
13
|
land discover plan build ship close
|
|
@@ -17,92 +17,85 @@ The **second brain for Forward Deployed Engineers** - engineers embedded at a cl
|
|
|
17
17
|
written as a side effect of the work
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
**You talk in plain language with `@fde`.** The agent (and an optional CLI) handles the boring memory work. You still confirm anything that goes into the record.
|
|
21
21
|
|
|
22
22
|
---
|
|
23
23
|
|
|
24
|
-
## The
|
|
25
|
-
|
|
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.
|
|
27
|
-
|
|
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.
|
|
24
|
+
## The week
|
|
29
25
|
|
|
30
|
-
|
|
26
|
+
Day to day you only need `@fde` and normal English. No command cheat sheet.
|
|
31
27
|
|
|
32
|
-
|
|
28
|
+
| When | What you say | What you get |
|
|
29
|
+
|------|--------------|--------------|
|
|
30
|
+
| **Start of week** | Open your AI coding agent (nothing to paste) | It already knows where you left off - trust, phase, what's next |
|
|
31
|
+
| **After a meeting** | `@fde` debrief these notes *(paste or attach them)* | Proposed updates to the record - you review, then confirm |
|
|
32
|
+
| **Before a stakeholder meeting** | `@fde` prep me for tomorrow's meeting with the sponsor | A short brief from what you already logged - not a blank chat |
|
|
33
|
+
| **Someone disputes scope** | `@fde` when did we agree to drop that feature? | Dated answers from the record (or a clear gap if nothing was logged) |
|
|
34
|
+
| **End of week** | `@fde` draft the sponsor update from the record | Status grounded in what actually happened |
|
|
33
35
|
|
|
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 |
|
|
36
|
+
Same client folder every time (`~/fde-engagements/<client>/.fde/`). Your AI coding agent reads it on every session. Optional terminal tools live under [Under the hood](#under-the-hood-optional).
|
|
41
37
|
|
|
42
38
|
---
|
|
43
39
|
|
|
44
40
|
## Quickstart
|
|
45
41
|
|
|
46
|
-
**1. Install** (
|
|
42
|
+
**1. Install** (pick one)
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
npx skills add suboss87/fdeops # Cursor, Codex, and skills-compatible agents
|
|
46
|
+
```
|
|
47
47
|
|
|
48
48
|
```text
|
|
49
|
-
/plugin marketplace add suboss87/fdeops
|
|
49
|
+
/plugin marketplace add suboss87/fdeops # Claude Code
|
|
50
50
|
/plugin install fdeops@fdeops
|
|
51
51
|
```
|
|
52
52
|
|
|
53
|
-
**2. Bind
|
|
53
|
+
**2. Bind once** - inside the client workspace (setup only; not a daily habit):
|
|
54
54
|
|
|
55
55
|
```bash
|
|
56
|
-
npx fdeops resume --init garvey
|
|
56
|
+
npx fdeops resume --init garvey # creates ~/fde-engagements/garvey engagement + binds workspace
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
|
|
59
|
+
**Check it worked:**
|
|
60
60
|
|
|
61
|
-
|
|
61
|
+
```bash
|
|
62
|
+
npx fdeops resume # prints a short "where we are" for this client
|
|
63
|
+
```
|
|
62
64
|
|
|
63
|
-
**3. Work**
|
|
65
|
+
**3. Work** - talk normally:
|
|
64
66
|
|
|
65
67
|
```text
|
|
66
68
|
@fde I just got the brief. New client, payments platform, they want it live before their Q3 audit.
|
|
67
69
|
```
|
|
68
70
|
|
|
69
|
-
`@fde`
|
|
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.
|
|
71
|
+
`@fde` routes and updates the fieldbook - you confirm judgment. Full workflow: [docs/USAGE.md](docs/USAGE.md).
|
|
72
72
|
|
|
73
73
|
<details>
|
|
74
|
-
<summary><strong>Other install paths</strong>
|
|
74
|
+
<summary><strong>Other install paths</strong> · scan · env</summary>
|
|
75
75
|
|
|
76
|
-
- **Cursor / Codex / Copilot / Gemini CLI:** `npx fdeops adapters .`
|
|
76
|
+
- **Cursor / Codex / Copilot / Gemini CLI:** `npx fdeops adapters .` - [adapters/](adapters/README.md)
|
|
77
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
78
|
- **Manual / air-gapped:** `git clone https://github.com/suboss87/fdeops.git && cd fdeops && node bin/install.js`
|
|
80
|
-
- **
|
|
81
|
-
- **
|
|
79
|
+
- **Try without install:** `npx fdeops scan` - day-1 recon (heuristic leads, not findings)
|
|
80
|
+
- **Requires:** [Node.js](https://nodejs.org) >= 18 for the CLI and adapters
|
|
81
|
+
- **Advanced:** `FDEOPS_ENGAGEMENT` overrides the workspace registry. Full matrix: [docs/install.md](docs/install.md)
|
|
82
82
|
|
|
83
83
|
</details>
|
|
84
84
|
|
|
85
85
|
---
|
|
86
86
|
|
|
87
|
-
##
|
|
88
|
-
|
|
89
|
-
This is the actual habit — the high-frequency loop, not the full skill matrix:
|
|
87
|
+
## How it works
|
|
90
88
|
|
|
91
|
-
- **
|
|
92
|
-
- **
|
|
93
|
-
- **
|
|
94
|
-
- **Friday** - `fde status` gives you the sponsor update from the week's actual record
|
|
89
|
+
- **You** describe the situation with `@fde` (or plain language once the skill is loaded)
|
|
90
|
+
- **Session start / end** - small hooks load where you left off and capture what changed (no re-paste)
|
|
91
|
+
- **Under the hood** - a local CLI does memory writes, search, and status with no model tokens; you do not need to learn it for daily use
|
|
95
92
|
|
|
96
|
-
|
|
93
|
+
fdeops complements repo memory: CLAUDE.md holds how the *code* works; the fieldbook holds how the *client engagement* works.
|
|
97
94
|
|
|
98
|
-
|
|
95
|
+
Works with **Claude Code** · **Cursor** · **Copilot** · **Gemini CLI** · **Ollama** · **LM Studio** - any model that reads markdown.
|
|
99
96
|
|
|
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:
|
|
97
|
+
<details>
|
|
98
|
+
<summary><strong>Phase verbs</strong> (land → close)</summary>
|
|
106
99
|
|
|
107
100
|
| Verb | When |
|
|
108
101
|
|------|------|
|
|
@@ -113,9 +106,9 @@ Two hooks and one router, on top of the fieldbook:
|
|
|
113
106
|
| **ship** | Going to production - pre-flight, canary, tested rollback |
|
|
114
107
|
| **close** | Engagement ending - handoff doc, retrospective, receipts that survive you |
|
|
115
108
|
|
|
116
|
-
Overlays for regulated domains (AI, fintech, healthcare, government) activate on signal.
|
|
109
|
+
Overlays for regulated domains (AI, fintech, healthcare, government) activate on signal. Full matrix: [docs/skills.md](docs/skills.md).
|
|
117
110
|
|
|
118
|
-
|
|
111
|
+
</details>
|
|
119
112
|
|
|
120
113
|
---
|
|
121
114
|
|
|
@@ -136,35 +129,52 @@ Every entry is dated and sourced, so you can defend it in front of skeptical sta
|
|
|
136
129
|
|
|
137
130
|
---
|
|
138
131
|
|
|
139
|
-
##
|
|
132
|
+
## Under the hood (optional)
|
|
133
|
+
|
|
134
|
+
**You do not need to learn these for daily work.** Chat with `@fde`; the agent runs the local tools. The list below is for setup, air-gap, or if you prefer the terminal.
|
|
140
135
|
|
|
141
|
-
|
|
136
|
+
**Humans only need (once / occasional):**
|
|
142
137
|
|
|
143
138
|
```bash
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
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)
|
|
139
|
+
npx fdeops resume --init <client> # one-time: create + bind this workspace
|
|
140
|
+
npx fdeops resume # check "where we are"
|
|
141
|
+
npx fdeops scan # try day-1 recon with no install
|
|
142
|
+
npx fdeops dashboard # optional local HTML view of the fieldbook
|
|
157
143
|
```
|
|
158
144
|
|
|
159
|
-
|
|
145
|
+
**What you say → what the agent runs** (you never have to type the right-hand side):
|
|
146
|
+
|
|
147
|
+
| You say | Agent runs |
|
|
148
|
+
|---------|------------|
|
|
149
|
+
| Debrief these notes | `fde debrief --smart …` → you confirm → `--apply` |
|
|
150
|
+
| Prep me for the sponsor meeting | `fde prep "…"` |
|
|
151
|
+
| When did we agree to drop that? | `fde receipts …` |
|
|
152
|
+
| Draft the sponsor update | `fde status` (+ judgment in chat) |
|
|
153
|
+
| Log that the sponsor went quiet | `fde log contact "…" --signal amber` |
|
|
154
|
+
|
|
155
|
+
<details>
|
|
156
|
+
<summary><strong>Full command list</strong> (power users / scripts)</summary>
|
|
160
157
|
|
|
161
|
-
|
|
158
|
+
```bash
|
|
159
|
+
fde triage # short status (also injected by session hooks)
|
|
160
|
+
fde debrief notes.md # if notes already use decision: / risk: / … prefixes
|
|
161
|
+
fde doctor # check the fieldbook for gaps
|
|
162
|
+
fde log decision "…"
|
|
163
|
+
fde log contact "…" --signal amber
|
|
164
|
+
fde dashboard --all # every client, sorted by trust
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Optional: `export FDEOPS_ENGAGEMENTS_ROOT=~/path/to/engagements` to isolate from `~/fde-engagements`.
|
|
168
|
+
|
|
169
|
+
Each `.fde/` is a local git repo (no remote, no telemetry). More detail: [docs/USAGE.md](docs/USAGE.md).
|
|
170
|
+
|
|
171
|
+
</details>
|
|
162
172
|
|
|
163
173
|
<p align="center"><img src="media/terminal-demo.svg" alt="fde CLI - status, scan, dashboard" width="720"/></p>
|
|
164
174
|
|
|
165
|
-
`fde dashboard`
|
|
175
|
+
Optional FieldBook view (`fde dashboard`) - current engagement by default:
|
|
166
176
|
|
|
167
|
-
<p align="center"><img width="1336" height="624" alt="
|
|
177
|
+
<p align="center"><img width="1336" height="624" alt="fde dashboard FieldBook" src="https://github.com/user-attachments/assets/5683614c-7730-4a3a-860d-185053a377eb" /></p>
|
|
168
178
|
|
|
169
179
|
---
|
|
170
180
|
|
|
@@ -196,10 +206,8 @@ Details: [PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
|
|
|
196
206
|
|
|
197
207
|
- **The artifact is the memory** - producing work and recording it are one action
|
|
198
208
|
- **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
209
|
- **Brief is a hypothesis** - discover before building the wrong thing
|
|
201
210
|
- **Evidence on every claim** - these files get defended in front of skeptical clients
|
|
202
|
-
- **Thin slices** - ship learning, not theatre
|
|
203
211
|
- **One customer, one folder** - context never bleeds
|
|
204
212
|
|
|
205
213
|
---
|
|
@@ -207,6 +215,8 @@ Details: [PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
|
|
|
207
215
|
## Updating
|
|
208
216
|
|
|
209
217
|
```bash
|
|
218
|
+
# Plugin / skills install: re-run the install command from Quickstart
|
|
219
|
+
# From a git clone:
|
|
210
220
|
cd fdeops && git pull && node bin/install.js
|
|
211
221
|
```
|
|
212
222
|
|
package/adapters/cursor.fde.mdc
CHANGED
|
@@ -9,10 +9,11 @@ You are the AI coding agent for a **Forward Deployed Engineer (FDE)** - the huma
|
|
|
9
9
|
|
|
10
10
|
## Entry
|
|
11
11
|
|
|
12
|
-
When the FDE types **`@fde`** or describes an engagement situation (new customer,
|
|
12
|
+
When the FDE types **`@fde`** or describes an engagement situation in plain language (new customer, meeting notes, prep for a stakeholder meeting, scope dispute, ready to ship), load the skill and route.
|
|
13
13
|
|
|
14
14
|
- Skill (single source of truth): `~/.claude/skills/fde/SKILL.md`
|
|
15
15
|
- **Never ask the FDE to pick a skill.** Read the situation, route silently, do the work.
|
|
16
|
+
- **Never ask the FDE to type `fde …` commands.** You run the local CLI; they confirm judgment in chat.
|
|
16
17
|
|
|
17
18
|
## Engagement memory
|
|
18
19
|
|
|
@@ -20,7 +21,7 @@ Read and write engagement files under the workspace's bound engagement: run `fde
|
|
|
20
21
|
|
|
21
22
|
**On every session entry (before other work):** run `fde triage` (fallback `node ~/.claude/fdeops/fde.js triage`, then `fde resume`). Lead with that TRIAGE block — trust, phase, open risks, next action, record owner/hash. Do not invent stakeholders or status.
|
|
22
23
|
|
|
23
|
-
|
|
24
|
+
You run the CLI for deterministic work - `fde scan | log | debrief | prep | doctor | receipts | status | dashboard` - instead of improvising shell or handing commands to the human.
|
|
24
25
|
|
|
25
26
|
### Meeting → memory loop
|
|
26
27
|
- Messy notes: `fde debrief --smart notes.md` → review `.debrief-propose` → `fde debrief --apply`
|
package/bin/check.js
CHANGED
|
@@ -111,7 +111,7 @@ for (const section of [
|
|
|
111
111
|
'Quickstart',
|
|
112
112
|
'Engagement memory',
|
|
113
113
|
'Who this is for',
|
|
114
|
-
'
|
|
114
|
+
'The week',
|
|
115
115
|
'Principles',
|
|
116
116
|
]) {
|
|
117
117
|
if (!readme.includes(section)) fail(`README missing section: ${section}`)
|
|
@@ -205,6 +205,35 @@ const hook = read('hooks/session-start')
|
|
|
205
205
|
if (!hook.includes('FDEOPS_ENGAGEMENT')) {
|
|
206
206
|
fail('session-start hook must read FDEOPS_ENGAGEMENT env var')
|
|
207
207
|
} else ok('hook FDEOPS_ENGAGEMENT')
|
|
208
|
+
// Token discipline: SessionStart must not dump the full skill (L1 progressive disclosure).
|
|
209
|
+
// Strip comments before scanning for a real `cat …SKILL.md` / BOOTSTRAP inject.
|
|
210
|
+
const hookCode = hook.replace(/^[ \t]*#.*$/gm, '')
|
|
211
|
+
if (/\$\(cat\s+"\$BOOTSTRAP"\)|cat\s+"\$BOOTSTRAP"|cat\s+[^\n]*SKILL\.md/.test(hookCode)) {
|
|
212
|
+
fail('session-start must not cat SKILL.md - inject TRIAGE + bounded context + pointer only')
|
|
213
|
+
}
|
|
214
|
+
if (hookCode.includes('BOOTSTRAP=')) {
|
|
215
|
+
fail('session-start must not resolve BOOTSTRAP skill path for inject')
|
|
216
|
+
}
|
|
217
|
+
if (!/plain language with @fde|invoke @fde/.test(hook)) {
|
|
218
|
+
fail('session-start must include a lean @fde / plain-language pointer (not full skill)')
|
|
219
|
+
}
|
|
220
|
+
const skillBody = read('skills/fde/SKILL.md')
|
|
221
|
+
if (!skillBody.includes('Human surface vs agent plumbing')) {
|
|
222
|
+
fail('SKILL.md must define human NL surface vs agent CLI plumbing')
|
|
223
|
+
}
|
|
224
|
+
if (!/never tell the FDE to type|Never tell the FDE to type|never ask the human to type fde/i.test(skillBody)) {
|
|
225
|
+
fail('SKILL.md must forbid asking the human to type fde commands')
|
|
226
|
+
}
|
|
227
|
+
if (!skillBody.includes('fde prep')) {
|
|
228
|
+
fail('SKILL.md must route walk-in prep to fde prep')
|
|
229
|
+
}
|
|
230
|
+
if (!skillBody.includes('debrief --smart')) {
|
|
231
|
+
fail('SKILL.md must prefer fde debrief --smart for messy notes')
|
|
232
|
+
}
|
|
233
|
+
if (!/\btriage\b/.test(hook)) {
|
|
234
|
+
fail('session-start must still inject TRIAGE')
|
|
235
|
+
}
|
|
236
|
+
ok('session-start lean inject (no SKILL dump)')
|
|
208
237
|
|
|
209
238
|
// v3: write-side memory backstop
|
|
210
239
|
if (!fs.existsSync(path.join(root, 'hooks', 'session-stop'))) {
|
package/hooks/session-start
CHANGED
|
@@ -1,18 +1,10 @@
|
|
|
1
1
|
#!/bin/bash
|
|
2
|
-
# fdeops SessionStart -
|
|
2
|
+
# fdeops SessionStart - inject TRIAGE + bounded engagement context (not the full skill).
|
|
3
|
+
# Token discipline (L1 progressive disclosure): Claude/Cursor already discover @fde via
|
|
4
|
+
# skill metadata. Dumping skills/fde/SKILL.md here paid ~6-8k tokens every session even
|
|
5
|
+
# when the FDE was not doing field work. Load the skill body only when @fde triggers.
|
|
3
6
|
|
|
4
7
|
CONTEXT_FILE=""
|
|
5
|
-
BOOTSTRAP=""
|
|
6
|
-
|
|
7
|
-
for candidate in \
|
|
8
|
-
"${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/fde/SKILL.md}" \
|
|
9
|
-
"$(dirname "$0")/../skills/fde/SKILL.md" \
|
|
10
|
-
"$HOME/.claude/skills/fde/SKILL.md"; do
|
|
11
|
-
if [ -n "$candidate" ] && [ -f "$candidate" ]; then
|
|
12
|
-
BOOTSTRAP="$candidate"
|
|
13
|
-
break
|
|
14
|
-
fi
|
|
15
|
-
done
|
|
16
8
|
|
|
17
9
|
resolve_engagement_dir() {
|
|
18
10
|
local raw="$1"
|
|
@@ -143,9 +135,8 @@ bounded_context() {
|
|
|
143
135
|
|
|
144
136
|
CONTENT=""
|
|
145
137
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
fi
|
|
138
|
+
# Lean pointer only - never cat SKILL.md. Methods load on @fde / skill trigger.
|
|
139
|
+
CONTENT="${CONTENT}fdeops: engagement fieldbook active. Human speaks plain language with @fde - you (the agent) run the local fde CLI for memory plumbing; never ask the human to type fde commands. Load skills/fde/SKILL.md when @fde triggers.\n\n"
|
|
149
140
|
|
|
150
141
|
# Same TRIAGE block as `fde resume` / `fde triage` - Monday morning must not
|
|
151
142
|
# depend on the model remembering to run a CLI command. Prefer the installed
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fdeops",
|
|
3
|
-
"version": "3.9.
|
|
3
|
+
"version": "3.9.6",
|
|
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
|
@@ -1,17 +1,26 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: fde
|
|
3
|
-
description: Second brain for Forward Deployed Engineers.
|
|
3
|
+
description: Second brain for Forward Deployed Engineers. The human describes the situation in plain language with @fde - you route, run the local fde CLI for memory plumbing, and write the fieldbook. Never ask the human to type fde commands.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# @fde
|
|
7
7
|
|
|
8
8
|
## Audience (read this first)
|
|
9
9
|
|
|
10
|
-
- **FDE** = the **human** who types `@fde` in the chat.
|
|
10
|
+
- **FDE** = the **human** who types `@fde` (or plain language) in the chat.
|
|
11
11
|
- **You (the model)** = the **AI coding agent** running this skill - not a human colleague, not the client's staff.
|
|
12
12
|
|
|
13
13
|
When this skill says "ask the FDE," it means the human. When it says "write to `.fde/`," you (the AI) write the files.
|
|
14
14
|
|
|
15
|
+
## Human surface vs agent plumbing (non-negotiable)
|
|
16
|
+
|
|
17
|
+
| Who | Interface |
|
|
18
|
+
|-----|-----------|
|
|
19
|
+
| **FDE (human)** | `@fde` + natural language. Examples: "debrief these notes", "prep me for tomorrow's sponsor meeting", "when did we agree to drop that?", "draft the sponsor update". |
|
|
20
|
+
| **You (agent)** | Run the local `fde` CLI for deterministic memory work. Never tell the FDE to type `fde …` (except if setup is missing - then **you** run `fde resume --init <name>` after one clarifying question). |
|
|
21
|
+
|
|
22
|
+
If you catch yourself saying "run `fde debrief --smart notes.txt`" to the human - **stop**. Run it yourself (or write a temp notes file and run it), then show the human the result in plain language for confirm/reject.
|
|
23
|
+
|
|
15
24
|
## Purpose
|
|
16
25
|
|
|
17
26
|
The single entry point for an entire client engagement. Field methods cover the FDE lifecycle (land through close, plus daily verbs and overlays). The human FDE describes what is happening - new customer, mid-project takeover, production fire, quiet stakeholder, ready to ship. You read the engagement memory, route to the right method, **do the work**, and leave the memory updated so the next session starts where this one ended.
|
|
@@ -36,6 +45,7 @@ These stop confident fiction. They are not optional soft tips.
|
|
|
36
45
|
|
|
37
46
|
| Temptation | Gate |
|
|
38
47
|
|------------|------|
|
|
48
|
+
| Tell the FDE to run `fde debrief` / `fde prep` / `fde receipts` themselves | **Stop.** You run the CLI; they confirm results in plain language. |
|
|
39
49
|
| Invent a stakeholder, meeting, or quote to make the narrative rich | **Stop.** Write `unknown - ask: <question>`. One fake name poisons every real citation. |
|
|
40
50
|
| Route to a phase because it "feels senior" while the signal is muddy | **Stop.** Playback + one natural question, or name the ambiguity ("discover or rescue — leaning X because…"). |
|
|
41
51
|
| Fill `success.md` / `terrain.md` with plausible defaults when the brief is thin | **Stop.** Run **brief interrogation** in land/discover (one Q + GUESS + confidence) until you can write without guessing, or leave gaps explicit. |
|
|
@@ -54,23 +64,24 @@ When NOT to interrogate or challenge: unambiguous one-liners, mechanical ops, FD
|
|
|
54
64
|
|
|
55
65
|
**Engagement path - zero ceremony.** Run `fde resume` (fallback: `node ~/.claude/fdeops/fde.js resume`). The **workspace registry** (written once by `fde resume --init <name>`) is the normal path; resolution order is env var override → registry → pointer file → workspace-name match (read-only) → `./.fde`. Writes require a bind (or `FDEOPS_ENGAGEMENT`), not folder name alone. It prints a **bounded** view of `context.md` - the curated head (state, next action) plus the most recent activity, with the older session log collapsed (use `fde resume --full` when you genuinely need the whole history). If it reports NO ENGAGEMENT: confirm the client name in conversation (one question), then run `fde resume --init <name>` yourself - the one setup step; the FDE never runs setup commands. Never install fdeops on infrastructure the FDE does not control.
|
|
56
66
|
|
|
57
|
-
**
|
|
67
|
+
**You run the `fde` CLI for deterministic work - never improvise shell, never hand the command to the FDE:**
|
|
58
68
|
|
|
59
|
-
|
|
|
60
|
-
|
|
61
|
-
|
|
|
62
|
-
| Day-1
|
|
63
|
-
|
|
|
64
|
-
|
|
|
65
|
-
| "
|
|
66
|
-
|
|
|
67
|
-
|
|
|
69
|
+
| When the FDE says (approx.) | You run |
|
|
70
|
+
|-----------------------------|---------|
|
|
71
|
+
| (session entry / where are we) | `fde resume` or use injected TRIAGE; `fde resume --init <name>` only if unbound |
|
|
72
|
+
| Day-1 look at the repo | `fde scan` - then you interpret against the brief |
|
|
73
|
+
| "Debrief these notes" / pastes meeting notes | Prefer `fde debrief --smart <notes>` → show propose → on confirm `fde debrief --apply`. Fallback: structure `decision:`/`risk:`/`delivery:`/`contact:` lines yourself, show FDE, then `fde debrief` |
|
|
74
|
+
| "Prep me for the meeting with …" / walk-in brief | `fde prep "<short label>"` - present the brief in plain language; do not invent facts missing from `.fde/` |
|
|
75
|
+
| "When did we agree…?" / scope dispute | `fde receipts <term>` - answer with dates; no hit = gap, not proof |
|
|
76
|
+
| "Draft the sponsor update" / how are we doing | `fde status` then follow `references/status.md` for the narrative |
|
|
77
|
+
| "Log that they went quiet" / trust signal | `fde log contact "…" --signal amber\|green\|red` (after FDE confirms the read) |
|
|
78
|
+
| Want the HTML fieldbook | `fde dashboard` |
|
|
68
79
|
|
|
69
|
-
**The debrief verb.** When the FDE shares
|
|
80
|
+
**The debrief verb.** Highest-frequency loop. When the FDE shares notes or says "debrief": **you** run the smart path (write notes to a temp file if needed). Show the proposed routing in plain language. Only `--apply` (or pipe prefixed lines) after they confirm. Never ask them to run the CLI. Detail: `references/debrief.md`.
|
|
70
81
|
|
|
71
|
-
CLI missing → use the manual
|
|
82
|
+
CLI missing → use the manual fallbacks inside each reference (still you write files; still never ask the FDE to run setup).
|
|
72
83
|
|
|
73
|
-
**Token model - where the cost goes.** Deterministic work is the CLI's job and costs **zero model tokens**: memory writes, recon, receipts, status, dashboard, and the bounded `fde resume`. Spend tokens only on judgment - reading the situation, routing, running the phase method, writing the artifact. Three rules keep a full day of FDE work cheap: load the router first and pull **one** reference only when you route to it; never dump a whole `.fde/` file into context - read the bounded resume, or `fde receipts <term>` for a targeted slice; don't re-read files you already have. The expensive model should fire for real decisions, not for plumbing the CLI already does.
|
|
84
|
+
**Token model - where the cost goes.** Deterministic work is the CLI's job and costs **zero model tokens**: memory writes, recon, receipts, status, dashboard, and the bounded `fde resume`. Session-start hooks inject **TRIAGE + bounded `context.md` + a one-line pointer** - never this full skill body (that loads only when `@fde` triggers). Spend tokens only on judgment - reading the situation, routing, running the phase method, writing the artifact. Three rules keep a full day of FDE work cheap: load the router first and pull **one** reference only when you route to it; never dump a whole `.fde/` file into context - read the bounded resume, or `fde receipts <term>` for a targeted slice; don't re-read files you already have. The expensive model should fire for real decisions, not for plumbing the CLI already does.
|
|
74
85
|
|
|
75
86
|
## Proactive intelligence (run on every session start)
|
|
76
87
|
|
|
@@ -241,6 +252,7 @@ Running the engagement and ending it well.
|
|
|
241
252
|
| Weekly update due, "need to send the sponsor something" | status | `references/status.md` |
|
|
242
253
|
| Demo coming up, show-and-tell, exec walkthrough | demo-prep | `references/demo-prep.md` |
|
|
243
254
|
| Just out of a meeting, raw notes, "they said…", "debrief" | debrief | the debrief verb (above) + `references/debrief.md` |
|
|
255
|
+
| Prep me for a meeting / walk-in brief / "what should I know before I talk to…" | - | run `fde prep "<label>"`, present in plain language |
|
|
244
256
|
| Sponsor's boss needs a summary, board update, justify continued investment | exec-narrative | `references/exec-narrative.md` |
|
|
245
257
|
| Status across all my customers | dashboard | `references/dashboard.md` |
|
|
246
258
|
| Juggling 2+ customers, losing track, context-switching | multi-customer-ops | `references/multi-customer-ops.md` |
|
|
@@ -1,36 +1,51 @@
|
|
|
1
1
|
# debrief - capture the meeting before it evaporates
|
|
2
2
|
|
|
3
|
-
**Enter when:** the FDE just left a meeting/call and dumps raw notes, a transcript, or "they said…".
|
|
3
|
+
**Enter when:** the FDE just left a meeting/call and dumps raw notes, a transcript, or "they said…". Highest-frequency moment in FDE life. Capture within the hour.
|
|
4
4
|
|
|
5
|
-
**Read first:** `context.md`, `stakeholders.md` (
|
|
5
|
+
**Read first:** `context.md`, `stakeholders.md` (signals against what's known).
|
|
6
|
+
|
|
7
|
+
**Who runs the CLI:** you (the agent). Never tell the FDE to type `fde debrief …`.
|
|
6
8
|
|
|
7
9
|
## Method (you do this work)
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
### Preferred path - smart debrief (messy notes)
|
|
12
|
+
|
|
13
|
+
1. Save the FDE's notes to a temp `.md` file in the workspace (or pipe stdin).
|
|
14
|
+
2. Run `fde debrief --smart <notes.md>` (or `npx fdeops debrief --smart …`).
|
|
15
|
+
3. Show the **proposed** routing in plain language (what would become decisions, risks, contacts, etc.).
|
|
16
|
+
4. On FDE confirm → run `fde debrief --apply`.
|
|
17
|
+
5. On reject → stop; ask what to change; do not apply.
|
|
18
|
+
|
|
19
|
+
No invented names or quotes. If the propose looks wrong, fix with judgment then re-propose or use the fallback path.
|
|
20
|
+
|
|
21
|
+
### Fallback - you structure, then route
|
|
22
|
+
|
|
23
|
+
If `--smart` is unavailable or the notes are already cleanly prefixed:
|
|
10
24
|
|
|
11
|
-
1.
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
25
|
+
1. Extract into buckets - **only what was actually said**:
|
|
26
|
+
- **Decisions** - agreed, by whom, in their words where possible
|
|
27
|
+
- **Action items** - owner + due; unowned → `owner: unknown - ask`
|
|
28
|
+
- **Stakeholder signals** - tone shifts with evidence → green/amber/red
|
|
29
|
+
- **Risks** - new / confirmed / retired
|
|
30
|
+
- **Open questions** - what to chase next
|
|
31
|
+
2. Format lines as `decision:` / `risk:` / `delivery:` / `contact:` (contacts may end with `[signal:green|amber|red]`).
|
|
32
|
+
3. Show that structured version to the FDE for confirmation.
|
|
33
|
+
4. Pipe to `fde debrief` (or write a file and run it).
|
|
16
34
|
|
|
17
|
-
|
|
35
|
+
One clarifying question max if the dump is ambiguous - then write. Never stall capture on completeness.
|
|
18
36
|
|
|
19
|
-
## Artifact
|
|
37
|
+
## Artifact
|
|
20
38
|
|
|
21
|
-
-
|
|
22
|
-
-
|
|
23
|
-
- Risks → `risks.md`, dated.
|
|
24
|
-
- Action items + open questions → `context.md` under "Next actions".
|
|
25
|
-
- Sacred/sensitive things mentioned (data, systems, politics) → `trust-profile.md` if new.
|
|
39
|
+
- Smart apply / debrief CLI writes the dated routes into the right `.fde/` files.
|
|
40
|
+
- If you must write directly: decisions → `decisions.md`; signals → `stakeholders.md` Signal history; risks → `risks.md`; next actions → `context.md`. Prefer the CLI.
|
|
26
41
|
|
|
27
42
|
## Checkpoint
|
|
28
43
|
|
|
29
|
-
Read back the 2
|
|
44
|
+
Read back the 2-3 most consequential captures in one breath - so the FDE can correct on the spot. Then stop. No summary theatre.
|
|
30
45
|
|
|
31
46
|
## Principles
|
|
32
47
|
|
|
33
|
-
- Capture within the hour or lose the nuance
|
|
34
|
-
-
|
|
35
|
-
- Signals move on evidence, never on
|
|
36
|
-
- A meeting
|
|
48
|
+
- Capture within the hour or lose the nuance.
|
|
49
|
+
- Verbatim quote outranks paraphrase; hesitation outranks quote.
|
|
50
|
+
- Signals move on evidence, never on vibe alone.
|
|
51
|
+
- A meeting with no decisions and no actions - say so; that is a finding.
|