fdeops 3.20.0 → 3.21.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/AGENTS.md +1 -1
- package/README.md +119 -115
- package/bin/check.js +2 -2
- package/mcp/fdeops-ingest/package.json +1 -1
- package/package.json +2 -2
- package/plugin.json +2 -2
- package/skills/fde/SKILL.md +3 -3
- package/skills/fde/references/discover.md +20 -6
- package/skills/fde/references/encode-pattern.md +1 -0
- package/skills/fde/references/eval-pack.md +3 -3
- package/skills/fde/references/land.md +4 -4
- package/skills/fde/references/poc.md +4 -1
- package/skills/fde/references/readout.md +4 -3
- package/skills/fde/references/review.md +2 -2
- package/skills/fde/references/runbook.md +4 -2
- package/skills/fde/references/ship.md +6 -2
- package/skills/fde/references/test-assumptions.md +18 -7
- package/skills/fde/references/three-options.md +17 -10
- package/templates/.fde/README.md +1 -1
- package/templates/.fde/assumptions.md +3 -2
package/AGENTS.md
CHANGED
|
@@ -4,7 +4,7 @@ This repository **is** fdeops - the engagement record for Forward Deployed Engin
|
|
|
4
4
|
|
|
5
5
|
## If you are helping use fdeops in an engagement
|
|
6
6
|
|
|
7
|
-
Route via **`@fde`** - read `skills/fde/SKILL.md` (the single source of truth),
|
|
7
|
+
Route via **`@fde`** - read `skills/fde/SKILL.md` (the single source of truth), route to one `references/*.md`, do the work, and write `.fde/` memory. Never ask the human to pick a skill. Other tools get the same behavior through thin pointer files in [`adapters/`](adapters/README.md).
|
|
8
8
|
|
|
9
9
|
## If you are contributing to this repository
|
|
10
10
|
|
package/README.md
CHANGED
|
@@ -2,91 +2,76 @@
|
|
|
2
2
|
|
|
3
3
|
**Forward deployed engineering skills for AI coding agents.**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
You're on a customer site. The AI coding agent writes code in their repo. This kit is the work around that code: the brief, who can say yes, proof on their staging then live, whether they signed off, whether they can run it after you leave.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Notes stay on your laptop. Their repo stays theirs. You confirm before anything is written down.
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
## Commands
|
|
9
|
+
<img width="1536" height="1024" alt="fdeops" src="https://github.com/user-attachments/assets/2bcb8739-55ee-445d-8a1a-8b38433b7b58" />
|
|
12
10
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
Six commands map to the embed. Each one loads `@fde`, which opens the skill for that moment: a thin brief pulls land, a wrong brief pulls discover, a Friday number pulls readout. Sprint or programme. Greenfield or brownfield. Any industry. You never pick from 30 names.
|
|
16
|
-
|
|
17
|
-
| Work | Command | Stage | Principle |
|
|
18
|
-
|------|---------|-------|-----------|
|
|
19
|
-
| Engage | `/brief` | Land | Name who signs done |
|
|
20
|
-
| Diagnose | `/discover` | Discover | Treat the brief as a hypothesis |
|
|
21
|
-
| Align | `/plan` | Plan | Work backwards from done |
|
|
22
|
-
| Deliver | `/ship` | Ship | One visible change, then go live |
|
|
23
|
-
| Realize | `/outcome` | Outcome | Promised, measured, accepted |
|
|
24
|
-
| Transfer | `/close` | Close | They operate it without you |
|
|
11
|
+
---
|
|
25
12
|
|
|
26
|
-
|
|
13
|
+
## Quick Start
|
|
27
14
|
|
|
28
|
-
|
|
29
|
-
|------|---------|-----------|
|
|
30
|
-
| Diagnose trust | `/trust` | Process gap, or they stopped trusting you |
|
|
31
|
-
| Find the receipt | `/receipts` | A dated line, or it did not happen |
|
|
32
|
-
| Capture the meeting | `/debrief` | Notes into the record |
|
|
33
|
-
| Prepare the meeting | `/prep` | One page from the record |
|
|
34
|
-
| Report the outcome | `/readout` | Promised, measured, accepted |
|
|
15
|
+
**Try it first, nothing installed.** In any repo:
|
|
35
16
|
|
|
36
|
-
|
|
17
|
+
```bash
|
|
18
|
+
npx fdeops scan
|
|
19
|
+
```
|
|
37
20
|
|
|
38
|
-
|
|
21
|
+
Two minutes. It prints what to look at on day one and the questions to ask. Local only, nothing written.
|
|
39
22
|
|
|
40
|
-
|
|
23
|
+
**Then install the skill:**
|
|
41
24
|
|
|
42
25
|
```bash
|
|
43
26
|
npx skills add suboss87/fdeops --skill fde
|
|
44
27
|
```
|
|
45
28
|
|
|
46
|
-
|
|
29
|
+
One chat. Name the client:
|
|
47
30
|
|
|
48
31
|
```text
|
|
49
|
-
@fde this is
|
|
32
|
+
@fde this is client01
|
|
50
33
|
```
|
|
51
34
|
|
|
52
|
-
Paste kickoff notes in the same thread. `@fde`
|
|
35
|
+
That creates `~/fde-engagements/client01/.fde/` on your laptop. Paste kickoff notes in the same thread. `@fde` picks what to check. You still decide.
|
|
36
|
+
|
|
37
|
+
Day to day: [docs/USAGE.md](docs/USAGE.md).
|
|
53
38
|
|
|
54
39
|
<details>
|
|
55
|
-
<summary><b>Claude Code
|
|
40
|
+
<summary><b>Claude Code</b></summary>
|
|
56
41
|
|
|
57
42
|
```text
|
|
58
43
|
/plugin marketplace add suboss87/fdeops
|
|
59
44
|
/plugin install fdeops@fdeops
|
|
60
45
|
```
|
|
61
46
|
|
|
62
|
-
Hooks
|
|
47
|
+
Hooks resume where you left off. Slash commands match the table below.
|
|
63
48
|
|
|
64
49
|
</details>
|
|
65
50
|
|
|
66
51
|
<details>
|
|
67
52
|
<summary><b>Cursor</b></summary>
|
|
68
53
|
|
|
54
|
+
After the skill install, in the **client repo** you have open (pointer, not a second pack):
|
|
55
|
+
|
|
69
56
|
```bash
|
|
70
|
-
npx
|
|
57
|
+
npx fdeops adapters .
|
|
71
58
|
```
|
|
72
59
|
|
|
73
|
-
|
|
60
|
+
See [adapters/](adapters/README.md).
|
|
74
61
|
|
|
75
62
|
</details>
|
|
76
63
|
|
|
77
64
|
<details>
|
|
78
|
-
<summary><b>
|
|
65
|
+
<summary><b>Air-gap, PATH, override</b></summary>
|
|
79
66
|
|
|
80
67
|
```bash
|
|
81
|
-
|
|
68
|
+
git clone https://github.com/suboss87/fdeops.git && node bin/install.js
|
|
82
69
|
```
|
|
83
70
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
Fallback if the agent cannot bind:
|
|
71
|
+
If the agent cannot create the folder:
|
|
87
72
|
|
|
88
73
|
```bash
|
|
89
|
-
npx fdeops resume --init
|
|
74
|
+
npx fdeops resume --init client01 # ~/fde-engagements/client01
|
|
90
75
|
```
|
|
91
76
|
|
|
92
77
|
Requires Node.js >= 18. Override: `FDEOPS_ENGAGEMENT`. See [docs/install.md](docs/install.md). Try the loop: `npx fdeops demo`.
|
|
@@ -95,13 +80,34 @@ Requires Node.js >= 18. Override: `FDEOPS_ENGAGEMENT`. See [docs/install.md](doc
|
|
|
95
80
|
|
|
96
81
|
---
|
|
97
82
|
|
|
83
|
+
## Commands
|
|
84
|
+
|
|
85
|
+
One command per stage. Skills load automatically.
|
|
86
|
+
|
|
87
|
+
Six stages, same order every job: Land, Discover, Plan, Ship, Outcome, Close.
|
|
88
|
+
|
|
89
|
+
| What you're doing | Command | Stage |
|
|
90
|
+
|-------------------|---------|-------|
|
|
91
|
+
| First days. Get the brief. Name who signs. | `/brief` | Land |
|
|
92
|
+
| Check the brief is the real job. | `/discover` | Discover |
|
|
93
|
+
| Sequence from done, not from the ticket. | `/plan` | Plan |
|
|
94
|
+
| Prove it on their staging, then go live. | `/ship` | Ship |
|
|
95
|
+
| What you promised, measured, and who accepted. | `/outcome` | Outcome |
|
|
96
|
+
| Hand it over. They run it without you. | `/close` | Close |
|
|
97
|
+
|
|
98
|
+
Same `@fde`, when you need them: `/debrief` (notes into the record), `/prep` (one page before you walk in), `/trust` (process gap, or they stopped trusting you), `/receipts` (a dated line, or it did not happen), `/readout` (Friday page for the sponsor; not a seventh stage).
|
|
99
|
+
|
|
100
|
+
You can also just say it: naming a client, a POC, changing their checkout, going live, asking what was agreed. A typo in a repo that is not a client job can skip this. A named client, a POC, or go-live cannot.
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
98
104
|
## All 30 Skills
|
|
99
105
|
|
|
100
|
-
|
|
106
|
+
Thirty situations, grouped by stage. Not prompts - each one has steps, a file it writes, and a checkpoint with you. Type English or a slash command. `@fde` opens the matching skill. You never pick one by name.
|
|
101
107
|
|
|
102
108
|
Full detail: [docs/skills-reference.md](docs/skills-reference.md).
|
|
103
109
|
|
|
104
|
-
### Land
|
|
110
|
+
### Land
|
|
105
111
|
|
|
106
112
|
| Skill | What it does | Use when |
|
|
107
113
|
|--------|--------------|----------|
|
|
@@ -111,7 +117,7 @@ Full detail: [docs/skills-reference.md](docs/skills-reference.md).
|
|
|
111
117
|
| [earn-trust](skills/fde/references/earn-trust.md) | Earn access | Need access or credibility |
|
|
112
118
|
| [hold-scope](skills/fde/references/hold-scope.md) | Hold scope | "Also can you…", timeline unchanged |
|
|
113
119
|
|
|
114
|
-
### Discover
|
|
120
|
+
### Discover
|
|
115
121
|
|
|
116
122
|
| Skill | What it does | Use when |
|
|
117
123
|
|--------|--------------|----------|
|
|
@@ -120,7 +126,7 @@ Full detail: [docs/skills-reference.md](docs/skills-reference.md).
|
|
|
120
126
|
| [score-use-cases](skills/fde/references/score-use-cases.md) | Score use cases | Everything is P0 |
|
|
121
127
|
| [poc](skills/fde/references/poc.md) | Validate the solution | POC, spike, need to de-risk |
|
|
122
128
|
|
|
123
|
-
### Plan
|
|
129
|
+
### Plan
|
|
124
130
|
|
|
125
131
|
| Skill | What it does | Use when |
|
|
126
132
|
|--------|--------------|----------|
|
|
@@ -129,7 +135,7 @@ Full detail: [docs/skills-reference.md](docs/skills-reference.md).
|
|
|
129
135
|
| [three-options](skills/fde/references/three-options.md) | Generate options | "What should we do?" |
|
|
130
136
|
| [pick-three](skills/fde/references/pick-three.md) | Prioritize three | Everything is urgent |
|
|
131
137
|
|
|
132
|
-
### Ship
|
|
138
|
+
### Ship
|
|
133
139
|
|
|
134
140
|
| Skill | What it does | Use when |
|
|
135
141
|
|--------|--------------|----------|
|
|
@@ -139,7 +145,7 @@ Full detail: [docs/skills-reference.md](docs/skills-reference.md).
|
|
|
139
145
|
| [review](skills/fde/references/review.md) | Review the change | Before merge, scope creep |
|
|
140
146
|
| [rollback](skills/fde/references/rollback.md) | Rehearse rollback | "We can always revert" |
|
|
141
147
|
|
|
142
|
-
### Outcome
|
|
148
|
+
### Outcome
|
|
143
149
|
|
|
144
150
|
| Skill | What it does | Use when |
|
|
145
151
|
|--------|--------------|----------|
|
|
@@ -151,7 +157,7 @@ Full detail: [docs/skills-reference.md](docs/skills-reference.md).
|
|
|
151
157
|
| [ingest](skills/fde/references/ingest.md) | Ingest sources | Transcript, Notion, Slack |
|
|
152
158
|
| [connect](skills/fde/references/connect.md) | Connect a source | Connect Granola |
|
|
153
159
|
|
|
154
|
-
### Close
|
|
160
|
+
### Close
|
|
155
161
|
|
|
156
162
|
| Skill | What it does | Use when |
|
|
157
163
|
|--------|--------------|----------|
|
|
@@ -161,7 +167,7 @@ Full detail: [docs/skills-reference.md](docs/skills-reference.md).
|
|
|
161
167
|
| [encode-pattern](skills/fde/references/encode-pattern.md) | Encode the pattern | It will apply again |
|
|
162
168
|
| [red-team](skills/fde/references/red-team.md) | Challenge the plan | "Poke holes in this" |
|
|
163
169
|
|
|
164
|
-
Overlays (on signal, not on request): [ai](skills/fde/references/ai.md) · [artifacts](skills/fde/references/artifacts.md) · [fintech](skills/fde/references/fintech.md) · [healthcare](skills/fde/references/healthcare.md) · [gov](skills/fde/references/gov.md)
|
|
170
|
+
Overlays (on signal, not on request): [ai](skills/fde/references/ai.md) · [artifacts](skills/fde/references/artifacts.md) · [fintech](skills/fde/references/fintech.md) · [healthcare](skills/fde/references/healthcare.md) · [gov](skills/fde/references/gov.md). AI companion (not a sixth overlay): [eval-pack](skills/fde/references/eval-pack.md).
|
|
165
171
|
|
|
166
172
|
Optional pull: you add the source MCP; we **pull** on request. [mcp/recipes/](mcp/recipes/)
|
|
167
173
|
|
|
@@ -169,33 +175,84 @@ Optional pull: you add the source MCP; we **pull** on request. [mcp/recipes/](mc
|
|
|
169
175
|
|
|
170
176
|
## How Skills Work
|
|
171
177
|
|
|
172
|
-
One
|
|
178
|
+
One `@fde`. One file per situation. One folder per client.
|
|
173
179
|
|
|
174
180
|
```
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
▼
|
|
178
|
-
skills/fde/SKILL.md hosts load this one file
|
|
181
|
+
"@fde this is client01" creates ~/fde-engagements/client01/.fde/
|
|
182
|
+
/brief or English the AI coding agent loads skills/fde/SKILL.md
|
|
179
183
|
│ routes. you never pick a skill by name
|
|
180
184
|
▼
|
|
181
|
-
references
|
|
185
|
+
references/<one>.md one skill, then stop
|
|
182
186
|
│
|
|
183
187
|
▼
|
|
184
188
|
fde CLI (local) dates, gates, redacts. no network
|
|
185
189
|
│ after you confirm
|
|
186
190
|
▼
|
|
187
|
-
~/fde-engagements
|
|
191
|
+
~/fde-engagements/client01/.fde/
|
|
188
192
|
```
|
|
189
193
|
|
|
190
|
-
**
|
|
194
|
+
**A dated line, or it did not happen.** Promised → measured → accepted. If it is not in `.fde/`, it is not on the record.
|
|
195
|
+
|
|
196
|
+
**Confirm, then it is written.** The CLI stays on your laptop: git and files, no network. The AI coding agent runs the command. You say yes. Then it is in the folder.
|
|
197
|
+
|
|
198
|
+
**The record is on your laptop.** Change hosts, install `@fde` on the new one, keep talking. The notes are not inside any vendor.
|
|
199
|
+
|
|
200
|
+
One skill hosts load: `skills/fde/SKILL.md`. It opens one file in `skills/fde/references/` and stops. Slash commands live in `.claude/commands/`. The local CLI is `bin/fde.js` (git + files, no network). Layout: [docs/REPO_LAYOUT.md](docs/REPO_LAYOUT.md).
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## Engagement memory (`.fde/`)
|
|
205
|
+
|
|
206
|
+
One folder per client. Plain markdown. Grep it, copy it, take it into a meeting.
|
|
207
|
+
|
|
208
|
+
| File | Holds |
|
|
209
|
+
|------|-------|
|
|
210
|
+
| `context.md` | Where you are |
|
|
211
|
+
| `brief.md` / `success.md` | What they asked; what “done” is and who signs |
|
|
212
|
+
| `reality.md` / `terrain.md` | The real problem; the map |
|
|
213
|
+
| `stakeholders.md` | `[signal:green\|amber\|red]` |
|
|
214
|
+
| `trust-profile.md` | Sacred data, AI policy, approval chain |
|
|
215
|
+
| `decisions.md` / `risks.md` / `delivery.md` | Dated choices; live risks; what shipped and how it rolls back |
|
|
216
|
+
|
|
217
|
+
Schema: [docs/schema.md](docs/schema.md). Local HTML: `npx fdeops dashboard`.
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## Who this is for
|
|
222
|
+
|
|
223
|
+
You sit with a customer's team. An AI coding agent writes in their repo. You need a record of the brief, who can say yes, what went live, and whether they signed off.
|
|
224
|
+
|
|
225
|
+
If you ship your own company's product from HQ, with no customer team that has to run it after you leave, you do not need this kit.
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## Your data stays yours
|
|
230
|
+
|
|
231
|
+
The **CLI** is local: git + files, no network, no telemetry. The **host model** sees `.fde/` the agent loads (usually a bounded `context.md`) and any client code you open. It must not see `<private>` blocks - redacted from CLI, dashboard, and hooks; do not paste them or open them with file tools. Nothing is written until you confirm. `~/fde-engagements` is in `$HOME`; iCloud/Dropbox is an NDA incident waiting.
|
|
232
|
+
|
|
233
|
+
[PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## Why FDEOps?
|
|
191
238
|
|
|
192
|
-
|
|
239
|
+
AI coding agents are built for a repo, not for a client. Left alone they skip who signs, whether the brief is true, and whether anyone accepted the number. Monday they start from the ticket again.
|
|
193
240
|
|
|
194
|
-
|
|
241
|
+
This is the kit you take on site. `@fde` runs the client work around the code. A local command dates every decision. The notes are markdown on your laptop. You confirm; then it is on the record.
|
|
195
242
|
|
|
196
|
-
|
|
243
|
+
---
|
|
197
244
|
|
|
198
|
-
|
|
245
|
+
## Principles
|
|
246
|
+
|
|
247
|
+
- **Who signs** - name them in the first days
|
|
248
|
+
- **Brief vs real job** - check the floor, not only the slide
|
|
249
|
+
- **Back from done** - sequence from signed-off, not from the ticket
|
|
250
|
+
- **Their staging then live** - prove it where they operate, then go live
|
|
251
|
+
- **Promised, measured, accepted** - a number nobody signed is claimed, not delivered
|
|
252
|
+
- **They run it** - if they cannot operate it without you, you are not done
|
|
253
|
+
- **A dated line, or it did not happen** - these files get defended in the room
|
|
254
|
+
- **One customer, one folder** - context never bleeds
|
|
255
|
+
- **The kit says what to check. You still decide.**
|
|
199
256
|
|
|
200
257
|
---
|
|
201
258
|
|
|
@@ -258,7 +315,7 @@ fdeops/
|
|
|
258
315
|
├── bin/ # local CLI: git + files, no network
|
|
259
316
|
├── hooks/ # session-start / session-stop / pre-compact
|
|
260
317
|
├── adapters/ # Cursor, Gemini, Copilot, Codex pointers
|
|
261
|
-
├── templates/.fde/ # memory files created on
|
|
318
|
+
├── templates/.fde/ # memory files created on first client
|
|
262
319
|
├── examples/ # fictional walkthroughs
|
|
263
320
|
├── mcp/ # optional ingest + source recipes
|
|
264
321
|
├── evals/ # routing checks
|
|
@@ -267,59 +324,6 @@ fdeops/
|
|
|
267
324
|
|
|
268
325
|
---
|
|
269
326
|
|
|
270
|
-
## Why FDEOps?
|
|
271
|
-
|
|
272
|
-
AI coding agents are built for a repo, not for a client. Left alone they skip who signs done, whether the brief is true, and whether anyone accepted the number. Monday morning they start from the ticket again.
|
|
273
|
-
|
|
274
|
-
FDEOps is the catalog you take on site. One `@fde` skill runs the embed from discovery to signed outcome: POC, their codebase, go-live, eval when a model judges, promised → measured → accepted. A local CLI dates every decision. `.fde/` is markdown on your laptop. You confirm; then it is on the record.
|
|
275
|
-
|
|
276
|
-
---
|
|
277
|
-
|
|
278
|
-
## Engagement memory (`.fde/`)
|
|
279
|
-
|
|
280
|
-
One folder per client. Plain markdown. Grep it, copy it, defend it.
|
|
281
|
-
|
|
282
|
-
| File | Holds |
|
|
283
|
-
|------|-------|
|
|
284
|
-
| `context.md` | Where you are |
|
|
285
|
-
| `brief.md` / `success.md` | What they asked; what “done” is and who signs |
|
|
286
|
-
| `reality.md` / `terrain.md` | The real problem; the map |
|
|
287
|
-
| `stakeholders.md` | `[signal:green\|amber\|red]` |
|
|
288
|
-
| `trust-profile.md` | Sacred data, AI policy, approval chain |
|
|
289
|
-
| `decisions.md` / `risks.md` / `delivery.md` | Dated choices; live risks; what shipped and how it rolls back |
|
|
290
|
-
|
|
291
|
-
Schema: [docs/schema.md](docs/schema.md). Local HTML: `npx fdeops dashboard`.
|
|
292
|
-
|
|
293
|
-
---
|
|
294
|
-
|
|
295
|
-
## Who this is for
|
|
296
|
-
|
|
297
|
-
You embed with a customer and an AI coding agent. Take this on the ground. Discovery through signed outcome lives in `@fde`. One `.fde/` per client so they do not blur.
|
|
298
|
-
|
|
299
|
-
If you only write code in your own repo with no client record to defend, you do not need this kit.
|
|
300
|
-
|
|
301
|
-
---
|
|
302
|
-
|
|
303
|
-
## Your data stays yours
|
|
304
|
-
|
|
305
|
-
Local only - `git` + files, no network, no telemetry. Plain markdown. The model sees client code only when you point the AI coding agent at it. `<private>` is redacted from CLI, dashboard, and hooks. Nothing is written until you confirm. `~/fde-engagements` is in `$HOME`; iCloud/Dropbox is an NDA incident waiting.
|
|
306
|
-
|
|
307
|
-
[PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
|
|
308
|
-
|
|
309
|
-
---
|
|
310
|
-
|
|
311
|
-
## Principles
|
|
312
|
-
|
|
313
|
-
- **One map** - any scale, greenfield or brownfield, any industry. Overlays carry the vertical
|
|
314
|
-
- **The artifact is the memory** - producing the work and recording it are one action
|
|
315
|
-
- **Ground loop** - name the change, characterise their code, prove it on their staging, go live, log the outcome
|
|
316
|
-
- **Skills, not autonomy** - the kit says what to check; judgment stays yours
|
|
317
|
-
- **Brief is a hypothesis** - discover before building the wrong thing
|
|
318
|
-
- **Evidence on every claim** - these files get defended in the room
|
|
319
|
-
- **One customer, one folder** - context never bleeds
|
|
320
|
-
|
|
321
|
-
---
|
|
322
|
-
|
|
323
327
|
## Contributing
|
|
324
328
|
|
|
325
329
|
**[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. [Issues](https://github.com/suboss87/fdeops/issues) · [Discussions](https://github.com/suboss87/fdeops/discussions) · [CONTRIBUTING.md](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md)
|
package/bin/check.js
CHANGED
|
@@ -153,8 +153,8 @@ ok(`router dispatch (${mentioned.length} reference targets verified) + memory co
|
|
|
153
153
|
}
|
|
154
154
|
if (!routed.size) fail('check.js could not parse the SKILL.md routing table')
|
|
155
155
|
|
|
156
|
-
// docs/skills-reference.md is the canonical per-
|
|
157
|
-
//
|
|
156
|
+
// docs/skills-reference.md is the canonical per-skill list: one row per
|
|
157
|
+
// skill inside the six stage tables, ending at the Overlays section.
|
|
158
158
|
const reference = read('docs/skills-reference.md')
|
|
159
159
|
const documented = new Set()
|
|
160
160
|
let documentedRows = 0
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fdeops",
|
|
3
|
-
"version": "3.
|
|
4
|
-
"description": "Forward deployed engineering skills for AI coding agents.
|
|
3
|
+
"version": "3.21.0",
|
|
4
|
+
"description": "Forward deployed engineering skills for AI coding agents. One @fde skill for the client work around the code: who can say yes, what went live, whether they signed off. Dated markdown on your laptop. You confirm each write.",
|
|
5
5
|
"bin": {
|
|
6
6
|
"fdeops": "bin/install.js",
|
|
7
7
|
"fde": "bin/fde.js"
|
package/plugin.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
|
|
3
3
|
"name": "fdeops",
|
|
4
|
-
"version": "3.
|
|
5
|
-
"description": "Forward deployed engineering skills for AI coding agents
|
|
4
|
+
"version": "3.21.0",
|
|
5
|
+
"description": "Forward deployed engineering skills for AI coding agents. One @fde skill for the client work around the code. You confirm; then it lands in .fde/ on your laptop.",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "Subash Natarajan",
|
|
8
8
|
"url": "https://github.com/suboss87"
|
package/skills/fde/SKILL.md
CHANGED
|
@@ -129,8 +129,8 @@ Work names (engage, diagnose, align, deliver, realize, transfer) are the same ma
|
|
|
129
129
|
|
|
130
130
|
| You hear | Skill | Reference |
|
|
131
131
|
|----------|-------|-----------|
|
|
132
|
-
| Diagnose, don't know the real problem, brief feels wrong, shadow processes, frame discovery, understand the problem space, data not ready, data estate, catalog the data | discover | `references/discover.md` |
|
|
133
|
-
| The brief feels too neat, assumptions untested, "we just need…", test assumptions | test-assumptions | `references/test-assumptions.md` |
|
|
132
|
+
| Diagnose, don't know the real problem, brief feels wrong, shadow processes, frame discovery, understand the problem space, data not ready, data estate, catalog the data, parts of the problem, decompose | discover | `references/discover.md` |
|
|
133
|
+
| The brief feels too neat, assumptions untested, "we just need…", test assumptions, inherited convention, why do we always | test-assumptions | `references/test-assumptions.md` |
|
|
134
134
|
| Multiple use cases competing, "we want to do everything", score use cases | score-use-cases | `references/score-use-cases.md` |
|
|
135
135
|
| Need to validate a direction, prototype, demo to de-risk, **POC**, spike, killer assumption, validate the solution, build prototype | poc | `references/poc.md` |
|
|
136
136
|
|
|
@@ -140,7 +140,7 @@ Work names (engage, diagnose, align, deliver, realize, transfer) are the same ma
|
|
|
140
140
|
|----------|-------|-----------|
|
|
141
141
|
| Align, break this down, what order, sequence the build, plan the roadmap, create user stories, write the tasks | plan | `references/plan.md` |
|
|
142
142
|
| Sponsor needs justification, need to defend budget or timeline, build the business case | business-case | `references/business-case.md` |
|
|
143
|
-
| Significant decision, multiple approaches, "what should we do?", generate solutions, generate options | three-options | `references/three-options.md` |
|
|
143
|
+
| Significant decision, multiple approaches, "what should we do?", generate solutions, generate options, not the playbook, from the surviving facts | three-options | `references/three-options.md` |
|
|
144
144
|
| 20 things are "urgent," need to pick the 3 that matter, prioritize three | pick-three | `references/pick-three.md` |
|
|
145
145
|
|
|
146
146
|
### Ship
|
|
@@ -54,6 +54,16 @@ Tests on **Question** - rewrite until all five hold:
|
|
|
54
54
|
|
|
55
55
|
Cannot write the Question → keep interrogating. Do not `fde scan`. Every later output of this phase aims at that Question. Sub-questions go to the operating map or `assumptions.md`, not into the Question.
|
|
56
56
|
|
|
57
|
+
## Parts of the problem (decompose only)
|
|
58
|
+
|
|
59
|
+
After the Question is locked, and **before** `fde scan` or any option: write what the problem is made of. No advice, no playbook, no solution.
|
|
60
|
+
|
|
61
|
+
If the stated brief hides a deeper job, name that deeper job in one sentence and **wait**. Do not silently replace their problem with yours.
|
|
62
|
+
|
|
63
|
+
In `terrain.md` under `## Parts`, list the smallest useful pieces that still change what you examine next. Typical cuts: people, process step, system, data, time, cost. For each piece: what it contains, and how it connects to the Question. Stop when a further split would not change where you dig.
|
|
64
|
+
|
|
65
|
+
Do not mark pieces as facts or assumptions here. That is `test-assumptions`. Do not assemble options here. That is `three-options`.
|
|
66
|
+
|
|
57
67
|
## Method - part 1: the codebase (you do this work)
|
|
58
68
|
|
|
59
69
|
**First move: `fde scan`** - it runs everything below deterministically in seconds (churn×tests, "temporary" archaeology, AI components, secrets redacted, previous attempts). Your job is then **interpretation**: read its output against the brief, follow the hotspots into the code, and connect the technical findings to the human signals in part 2.
|
|
@@ -127,9 +137,11 @@ When discovery requires a structured session with multiple stakeholders (alignme
|
|
|
127
137
|
|
|
128
138
|
**After the room:** Summary in `decisions.md` within 2 hours. Decisions decay - what felt clear at 3pm is debatable by 5pm if unwritten.
|
|
129
139
|
|
|
130
|
-
## Method - part 4: data estate
|
|
140
|
+
## Method - part 4: data estate and the pipe
|
|
141
|
+
|
|
142
|
+
Always map the estate before you score a use case - not only when someone said "AI." A path they cannot feed is a discover miss, not a ship surprise.
|
|
131
143
|
|
|
132
|
-
|
|
144
|
+
**Their words first.** In `terrain.md`, write the names the floor uses for the workaround, the sheet, the exception path, and the person who left. Later plan/ship/review sentences use those names. Do not translate their floor into generic product language.
|
|
133
145
|
|
|
134
146
|
**The 5 questions (ask the data owner, not the sponsor):**
|
|
135
147
|
1. **Where does data live?** - List every source: databases, warehouses, SaaS exports, spreadsheets, S3 buckets, vendor APIs. Map it.
|
|
@@ -138,13 +150,15 @@ When the engagement involves AI, analytics, or data-heavy automation, assess the
|
|
|
138
150
|
4. **What's the quality?** - Sample 100 rows from each critical source. Check: nulls, duplicates, format consistency, semantic correctness. A 60% null rate in a key field = that source is fiction.
|
|
139
151
|
5. **What are the governance constraints?** - PII classification, retention policies, cross-border rules, consent basis. One missed constraint = a compliance stop later.
|
|
140
152
|
|
|
153
|
+
**The pipe (what talks to what).** For each source that a use case depends on, write: the system it flows from and to, the contract (object, table, file, API), whose credentials, what happens when the vendor 500s or the Monday file does not land, and whether the join the sponsor described actually exists. Their IdP, CRM, and warehouse are delivery work when the path needs them - policy questions in `trust-profile.md` are not a substitute.
|
|
154
|
+
|
|
141
155
|
**The data readiness matrix:**
|
|
142
156
|
|
|
143
|
-
| Source | Location | Freshness | Owner | Quality (sample) | Governance | Verdict |
|
|
144
|
-
|
|
145
|
-
| _fill per source_ | | | | | | Ready / Needs work / Blocker |
|
|
157
|
+
| Source | Location | Freshness | Owner | Quality (sample) | Governance | Pipe | Verdict |
|
|
158
|
+
|--------|----------|-----------|-------|-----------------|------------|------|---------|
|
|
159
|
+
| _fill per source_ | | | | | | | Ready / Needs work / Blocker |
|
|
146
160
|
|
|
147
|
-
A use case that depends on a "Blocker" source doesn't get scored - it gets a
|
|
161
|
+
A use case that depends on a "Blocker" source **or a Blocker pipe** doesn't get scored - it gets a remediation conversation first. `what-breaks` finding an invisible integration at ship is already too late. Write this to `terrain.md` under a `## Data estate` section.
|
|
148
162
|
|
|
149
163
|
## When scope is a transformation, not a single problem
|
|
150
164
|
|
|
@@ -47,6 +47,7 @@ The difference between a 5-year FDE and a 15-year FDE is not talent - it's encod
|
|
|
47
47
|
| **Specific enough?** | Contains concrete steps, not just principles | "Build trust" / "Communicate well" - too vague to act on |
|
|
48
48
|
| **Repeatable?** | Applies to a class of situations, not just this one | Only worked because of a unique circumstance |
|
|
49
49
|
| **Falsifiable?** | You can tell when the pattern is working or not | No way to measure whether applying it helped |
|
|
50
|
+
| **Monday bag?** | You would refuse the next similar embed without this in your bag - a named move plus an artifact you can drop on day one (pipe questions, CAB dance, eval golden shape, floor-drill script) | "We learned to communicate." Patterns that only live in this client's `.fde/` do not compound |
|
|
50
51
|
|
|
51
52
|
**4. Classify by stage.** Patterns sort into the same stages as the skills:
|
|
52
53
|
|
|
@@ -22,9 +22,9 @@ Intelligence without evidence is token-maxing with a nicer name. An FDE earns tr
|
|
|
22
22
|
|
|
23
23
|
**3. Score pass/fail, not vibes.** Run the suite. Record count pass / fail. Failures get a failure-mode tag (missing data, wrong record, format drift, hallucination, retrieval miss, unsafe action, other).
|
|
24
24
|
|
|
25
|
-
**4. Human-in-the-loop gate.** Name which outcomes require human approve before side effects.
|
|
25
|
+
**4. Human-in-the-loop gate.** Name which outcomes require human approve before side effects. Judgement that has a side effect (write, send, transfer, ticket, deploy, pay, page) is **NO-SHIP** without a named human on their side in the loop. Do not write "none - allowed under policy" to bless lights-out write-access. Staging may run a supervised loop with a kill switch, a cost cap, and a golden set from **their** failures. Production stays gated until they have a written policy, a named owner, and dated eval receipts on real traffic.
|
|
26
26
|
|
|
27
|
-
**5. Ship rule.** Until `evals.md` shows Verdict **SHIP** with a dated run (critical fails = 0) and HITL filled
|
|
27
|
+
**5. Ship rule.** Until `evals.md` shows Verdict **SHIP** with a dated run (critical fails = 0) and HITL filled, AI-touching ship stays **fix-first**. Eval fails do not sit in a backlog - they reopen plan (descope, move the judgement, or kill the path). Log a one-line eval receipt in `delivery.md` → `## Ship receipts`. No "probably fine."
|
|
28
28
|
|
|
29
29
|
## Artifact - `evals.md`
|
|
30
30
|
|
|
@@ -39,5 +39,5 @@ Present to the FDE: suite size, pass rate, top failure mode, HITL gate, Verdict
|
|
|
39
39
|
- No golden set, no AI ship.
|
|
40
40
|
- Pass/fail beats “looks good.”
|
|
41
41
|
- Failure modes are the product - the happy path is table stakes.
|
|
42
|
-
- HITL is a gate, not a slide.
|
|
42
|
+
- HITL is a gate, not a slide. Side effects without a named human on their side are NO-SHIP.
|
|
43
43
|
- Non-AI work does not need this file.
|
|
@@ -99,12 +99,12 @@ If `stakeholders.md` already has a `## Signal history` section (it does from the
|
|
|
99
99
|
|
|
100
100
|
**`trust-profile.md`** - sacred data (`<private>` tagged), fears heard, AI policy, approval chain. Sensitive: skip for status reads; use CLI/redacted surfaces; never paste raw `<private>` into prompts or subagents.
|
|
101
101
|
|
|
102
|
-
**`assumptions.md`** - seed every unverified claim from the brief (and the day-1 hypothesis) as rows with blast radius CRITICAL / LOAD-BEARING / CONVENIENCE and status `OPEN`. Do not wait for test-assumptions - land makes the register exist. Example:
|
|
102
|
+
**`assumptions.md`** - seed every unverified claim from the brief (and the day-1 hypothesis) as rows with Kind `UNKNOWN` (or `CONVENTION` if they said "we always"), blast radius CRITICAL / LOAD-BEARING / CONVENIENCE, and status `OPEN`. Do not wait for test-assumptions - land makes the register exist. Example:
|
|
103
103
|
|
|
104
104
|
```markdown
|
|
105
|
-
| # | Assumption | Blast radius | How we test | Status | Evidence |
|
|
106
|
-
|
|
107
|
-
| 1 | <claim from brief> | CRITICAL | <cheapest falsifying test> | OPEN | (stated, unverified) |
|
|
105
|
+
| # | Assumption | Kind | Blast radius | How we test | Status | Evidence |
|
|
106
|
+
|---|------------|------|--------------|-------------|--------|----------|
|
|
107
|
+
| 1 | <claim from brief> | UNKNOWN | CRITICAL | <cheapest falsifying test> | OPEN | (stated, unverified) |
|
|
108
108
|
```
|
|
109
109
|
|
|
110
110
|
One falsifiable hypothesis about the real problem also goes at the bottom of `brief.md` - discover / test-assumptions will test it.
|
|
@@ -8,7 +8,9 @@ A green check on synthetic data is not a validated solution. The person who can
|
|
|
8
8
|
|
|
9
9
|
## Method (you do this work)
|
|
10
10
|
|
|
11
|
-
**0. Name the killer assumption.** With the FDE: "What's the belief that kills the project if it's wrong?" Prototype **that** - not the pretty demo.
|
|
11
|
+
**0. Name the killer assumption.** With the FDE: "What's the belief that kills the project if it's wrong?" Prototype **that** - not the pretty demo. If `three-options` just ran: the cheapest test is for the recommended option first, unless they pick another.
|
|
12
|
+
|
|
13
|
+
**0b. Pass / fail before you build.** For the test you will run, write three lines in `prototype-log.md` first: what you will actually do (who you talk to, what you show, on whose screen); the result that **kills** this option; the result that keeps it alive. What you would learn either way. If every option's test would fail, name which `assumptions.md` block to reopen - do not invent a fourth playbook.
|
|
12
14
|
|
|
13
15
|
**1. Pick by score when several use cases compete.** Use the scoring model from `discover.md` - (Value × Data readiness) / Complexity. If discover already scored, reuse; never re-score independently.
|
|
14
16
|
|
|
@@ -37,6 +39,7 @@ Tell the FDE: did the riskiest assumption hold · what the customer's reaction a
|
|
|
37
39
|
## Principles
|
|
38
40
|
|
|
39
41
|
- Speed of learning beats code quality. Never more than a day.
|
|
42
|
+
- Write pass/fail before you build. A demo with no kill line is a show.
|
|
40
43
|
- Show it rough. Polish misleads.
|
|
41
44
|
- Prototype the killer assumption, not the demo.
|
|
42
45
|
- Kill fast; log the learning.
|
|
@@ -12,15 +12,16 @@
|
|
|
12
12
|
|
|
13
13
|
| Block | What to write | Source |
|
|
14
14
|
|-------|---------------|--------|
|
|
15
|
-
| **S - Situation** | Where we are against `success.md`, in their words | success.md, delivery value ledger |
|
|
15
|
+
| **S - Situation** | Where we are against `success.md`, in their words - including whether the floor still uses the old path | success.md, delivery value ledger, reality.md workaround |
|
|
16
16
|
| **C - Complication** | What changed, what is at risk, or what we learned (bad news first) | risks.md, assumptions DISPROVED/OPEN, stakeholders signal |
|
|
17
17
|
| **Q - Question / Ask** | The one decision or help you need from them | decisions.md, access/sign-off needs |
|
|
18
18
|
| **A - Answer** | What you recommend / what happens next week (≤3 bullets) | plan Now lane, delivery promised→measured |
|
|
19
19
|
|
|
20
20
|
Then add, still on the same page:
|
|
21
21
|
1. **Value this week** - from the value ledger: promised → measured (or "pending") → **accepted by whom**, with evidence citation. A measured number nobody on the customer side has agreed to is written as `claimed`, and the Ask never rests on it - if the whole case for the next phase is a claimed number, the real ask this week is "who signs off that this is real?".
|
|
22
|
-
2. **
|
|
23
|
-
3. **
|
|
22
|
+
2. **Are they using it?** - Situation must say whether the workaround is still open: spreadsheet still running, shadow paste still happening, named operator completed Tuesday's job on the new path without you at the keyboard. A measured metric with the old path still live is `claimed`. That week's Ask is not "fund phase 2." It is "who on their side stops the old way, by when."
|
|
23
|
+
3. **Kill / defer reminder** - one line from the plan kill list so scope fights stay visible.
|
|
24
|
+
4. **Hostile Q prep** - three questions a skeptical sponsor will ask, with one-line answers from memory.
|
|
24
25
|
|
|
25
26
|
Exec voice: no jargon, no hedging, every claim traceable (`(shipped Tue, delivery.md)`). Draft in the **FDE's voice, for the FDE to send** - never send anything yourself.
|
|
26
27
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# review - Review the change
|
|
2
2
|
|
|
3
|
-
**Enter when:** a change needs review before merge - "is this safe," "does it match what we agreed."
|
|
3
|
+
**Enter when:** a change needs review before merge - "is this safe," "does it match what we agreed." Their team commented on the PR: same skill. Comments are to check, not to obey.
|
|
4
4
|
|
|
5
5
|
**Read first:** `context.md`, `decisions.md`, `trust-profile.md`, `terrain.md`. Not `reality.md`/`stakeholders.md` - irrelevant to reviewing code against agreed scope.
|
|
6
6
|
|
|
@@ -52,7 +52,7 @@ Five dimensions, line-specific ("line 47 fails under concurrent writes - no lock
|
|
|
52
52
|
|
|
53
53
|
1. Read the full diff before commenting.
|
|
54
54
|
2. Verdicts: **Stage 1: Pass / Blocked (reason)** · **Stage 2: Pass / Concerns (line-specific)**.
|
|
55
|
-
3. Fix only **real** findings tied to this change - no drive-by refactors. Reject false positives with one sentence why.
|
|
55
|
+
3. Fix only **real** findings tied to this change - no drive-by refactors. Reject false positives with one sentence why. Their comments are to check, not to obey. Restate each against the one-line intent and `trust-profile.md`. One item unclear → ask before changing any of them. If it breaks a signed constraint, a sacred system, or nothing calls it: one-sentence pushback, then wait.
|
|
56
56
|
4. Add or update a test per bug found where possible.
|
|
57
57
|
5. Re-run tests/typechecks - state what ran.
|
|
58
58
|
6. Re-review. Repeat until Pass/Pass or a human must decide scope/product.
|
|
@@ -60,6 +60,7 @@ Rollback: <exact command and expected time>
|
|
|
60
60
|
|---------|-------|-----------|----------|--------|
|
|
61
61
|
| **Architecture walkthrough** | Why, not what. The decisions, the trade-offs, the things that almost went wrong. | Full team | 60-90 min | Recording + Q&A log |
|
|
62
62
|
| **Operational drill** | Deploy, rollback, incident response. They do it, you watch. | On-call team | 60 min | Drill report with confidence level |
|
|
63
|
+
| **Floor drill** | They run the real job (the exception on the operating map) while you watch, hands off. Then they teach the next person. If they cannot, the runbook is a PDF. | Named operator on the floor | 45-60 min | They used the 2am doc during the drill, or the embed is not closed |
|
|
63
64
|
| **Edge-case handover** | The things that aren't in any document. The workarounds, the fragile spots, the "ask Sarah because she's the only one who knows." | Team lead + 1 | 30 min | Additions to `handoff.md` |
|
|
64
65
|
|
|
65
66
|
**4. The confidence check.** After the knowledge transfer, score the team's readiness:
|
|
@@ -68,11 +69,12 @@ Rollback: <exact command and expected time>
|
|
|
68
69
|
|------|------------------|----------|
|
|
69
70
|
| Daily operations | | Can they deploy and rollback without help? |
|
|
70
71
|
| Incident response | | Did they complete the drill within acceptable time? |
|
|
72
|
+
| Floor job | | Did the named operator complete Tuesday's real exception without you at the keyboard? |
|
|
71
73
|
| Architecture decisions | | Can they explain why the system is built this way? |
|
|
72
74
|
| AI components (if any) | | Do they know how to monitor, retrain, and disable? |
|
|
73
75
|
| Stakeholder management | | Do they know who to update and how? |
|
|
74
76
|
|
|
75
|
-
**Average below 3.5 → the handoff is not complete.** Extend
|
|
77
|
+
**Average below 3.5 → the handoff is not complete.** Extend, or tell the sponsor the embed is not closed. Do not document the gap and leave.
|
|
76
78
|
|
|
77
79
|
**5. The successor brief.** If a new FDE is taking over, write a brief that gets them operational in one hour:
|
|
78
80
|
|
|
@@ -132,7 +134,7 @@ If you see 2+: accelerate the handoff immediately. The longer you stay past usef
|
|
|
132
134
|
|
|
133
135
|
- The goal of every engagement is to make yourself replaceable.
|
|
134
136
|
- The 2am document is the real handoff - everything else supports it.
|
|
135
|
-
- Knowledge transfer is
|
|
137
|
+
- Knowledge transfer is four sessions, not a doc dump. The floor drill is the named operator completing Tuesday's real job from the 2am doc, hands off. If they cannot, do not close.
|
|
136
138
|
- A confidence score below 3.5 means the handoff isn't done.
|
|
137
139
|
- The successor brief gets the next FDE operational in one hour or it's too long.
|
|
138
140
|
- Clean exit: no personal credentials left behind, ever.
|
|
@@ -27,7 +27,7 @@ Skip POC only when the killer assumption already lives in the repo (typical brow
|
|
|
27
27
|
|
|
28
28
|
**Done means:** the signer in `success.md` can reject this on staging they operate. A green check on your laptop is not delivery. Do not start the next change until this one is rejectable.
|
|
29
29
|
|
|
30
|
-
If `terrain.md` **Data estate** lists a **Blocker** this change depends on: stop. That is discover, not ship. Do not build a path they cannot feed.
|
|
30
|
+
If `terrain.md` **Data estate** lists a **Blocker** this change depends on (source or pipe): stop. That is discover, not ship. Do not build a path they cannot feed.
|
|
31
31
|
|
|
32
32
|
## Method - one change they can see
|
|
33
33
|
|
|
@@ -72,10 +72,12 @@ Read existing code in the area (search before creating)
|
|
|
72
72
|
|
|
73
73
|
**Prove it on their staging.** A green check on your laptop is not delivery.
|
|
74
74
|
|
|
75
|
-
- Run **their** test command,
|
|
75
|
+
- Run **their** test command, on **their** CI, with **their** fixtures. Write the command and the result in `delivery.md`. You do not add a runner they will not keep. If you have not run their command in this turn, you cannot write that it passed. Last session's green, "should pass," and "looks correct" are not a receipt.
|
|
76
76
|
- If the signer in `success.md` cannot reject this on a screen they already use, it is not proven.
|
|
77
77
|
- Staging they operate beats a local demo. If you have no staging: `unknown - ask:` who owns an environment, then stop pretending it shipped.
|
|
78
|
+
- **Monday-shaped data.** Staging that is empty, synthetic, or last quarter is not next Tuesday. Before go-live, write what staging is missing (volume, PII, the batch that only runs in prod, the account that only exists in the warehouse) and what that means for the kill test. If the signer cannot reject it on a screen they already operate, with data that looks like next Tuesday, it is not proven.
|
|
78
79
|
- Model in the path: `eval-pack` until `evals.md` says SHIP. Do not skip because "it looked right in chat."
|
|
80
|
+
- A model drafts. A named human on their side ships. No unsupervised loop on their production. If the brief demands lights-out write-access, that is `who-decides` / `hold-scope`, not ship.
|
|
79
81
|
|
|
80
82
|
The proof is whatever this client already believes, plus one new receipt they can replay.
|
|
81
83
|
|
|
@@ -214,6 +216,8 @@ grep -rnE "(api[_-]?key|secret|password|token)\s*[:=]\s*['\"][^'\"]{8,}" \
|
|
|
214
216
|
|
|
215
217
|
**Canary:** 1-5% of traffic, ≥10 minutes. Watch error rate, latency, and **the business metric this change affects**. Anything looks wrong → roll back immediately; investigate safely; redeploy when confident. Never investigate during the canary. Then stage up: 5% → 25% → 100%, each confirmed stable.
|
|
216
218
|
|
|
219
|
+
**Canary receipt** (write it, or the canary did not happen): what was watched, on whose dashboard, for how long, and that the next change did not start in the window. If prod is a CAB console, vendor button, or their pipeline, write the owner and the click path - the host agent does not get to pretend it shipped.
|
|
220
|
+
|
|
217
221
|
**Programme-scale rollout (transformations)** - different problem from one service:
|
|
218
222
|
1. **Pilot** - one team, one use case; success metrics defined *before* it starts (after = fitting metrics to results).
|
|
219
223
|
2. **Limited release** - 3-5 teams, real load; this is where the failure modes the pilot hid show up.
|
|
@@ -8,7 +8,7 @@ Every engagement is built on assumptions. Most are invisible until they're wrong
|
|
|
8
8
|
|
|
9
9
|
## Method (you do this work)
|
|
10
10
|
|
|
11
|
-
**1. Extract the assumptions.** Read `brief.md` and `
|
|
11
|
+
**1. Extract the assumptions.** Read `brief.md`, `reality.md`, and `terrain.md` `## Parts` line by line. Every statement that isn't backed by evidence is an assumption. Treat every "obvious" block as a convention until a receipt proves it. Common hiding places:
|
|
12
12
|
|
|
13
13
|
| Where assumptions hide | Example | The real question |
|
|
14
14
|
|----------------------|---------|-------------------|
|
|
@@ -19,7 +19,17 @@ Every engagement is built on assumptions. Most are invisible until they're wrong
|
|
|
19
19
|
| **The data claim** | "We have good data for this" | Defined how? Validated when? By whom? Sample checked? |
|
|
20
20
|
| **The "just"** | "We just need to add a feature" | On what system? With what dependencies? What breaks? |
|
|
21
21
|
|
|
22
|
-
**2.
|
|
22
|
+
**2. Kind first, then blast radius.** For each row, classify:
|
|
23
|
+
|
|
24
|
+
| Kind | Meaning |
|
|
25
|
+
|------|---------|
|
|
26
|
+
| **FACT** | A dated receipt, a measurement, or the repo. You can point at it. |
|
|
27
|
+
| **CONVENTION** | How they have always done it. The playbook. "We just…" |
|
|
28
|
+
| **UNKNOWN** | No evidence either way. |
|
|
29
|
+
|
|
30
|
+
Order the list load-bearing first. For each CONVENTION or UNKNOWN, one line: what breaks if it is wrong, and what opens if you **invert** it (stop obeying it). A FACT with no receipt is UNKNOWN - do not promote it to protect the brief.
|
|
31
|
+
|
|
32
|
+
Then classify blast radius:
|
|
23
33
|
|
|
24
34
|
```
|
|
25
35
|
CRITICAL - if wrong, the engagement fails or the approach changes fundamentally
|
|
@@ -55,11 +65,11 @@ Evidence first, then the question. Let them reach the conclusion.
|
|
|
55
65
|
**`assumptions.md`** - this IS the register (create if land did not). Keep one live table; do not only bury results in `reality.md`:
|
|
56
66
|
|
|
57
67
|
```markdown
|
|
58
|
-
| # | Assumption | Blast radius | How we test | Status | Evidence |
|
|
59
|
-
|
|
60
|
-
| 1 | API is the bottleneck | CRITICAL | p95 instrumentation 24h | DISPROVED | 80% wait in DB layer (Day N) |
|
|
61
|
-
| 2 | Team will adopt new tool | LOAD-BEARING | 3 individual interviews | CONFIRMED | 2/3 describe a use case unprompted |
|
|
62
|
-
| 3 | Data clean enough for ML | CRITICAL | 200-record sample | PARTIAL → OPEN follow-up | 12% nulls on key field; cleaning task added |
|
|
68
|
+
| # | Assumption | Kind | Blast radius | How we test | Status | Evidence |
|
|
69
|
+
|---|------------|------|--------------|-------------|--------|----------|
|
|
70
|
+
| 1 | API is the bottleneck | CONVENTION | CRITICAL | p95 instrumentation 24h | DISPROVED | 80% wait in DB layer (Day N) |
|
|
71
|
+
| 2 | Team will adopt new tool | UNKNOWN | LOAD-BEARING | 3 individual interviews | CONFIRMED | 2/3 describe a use case unprompted |
|
|
72
|
+
| 3 | Data clean enough for ML | UNKNOWN | CRITICAL | 200-record sample | PARTIAL → OPEN follow-up | 12% nulls on key field; cleaning task added |
|
|
63
73
|
```
|
|
64
74
|
|
|
65
75
|
Status values: `OPEN` · `TESTING` · `CONFIRMED` · `DISPROVED` · `PARKED`. A CRITICAL row still `OPEN` blocks plan.
|
|
@@ -85,6 +95,7 @@ Result: acked in 40 minutes, by Marco, not finance. Assumption DISPROVED, and th
|
|
|
85
95
|
## Principles
|
|
86
96
|
|
|
87
97
|
- Every "just" is an assumption. Every "should" is an assumption.
|
|
98
|
+
- Kind before blast radius. A FACT with no receipt is UNKNOWN.
|
|
88
99
|
- Kill the riskiest, cheapest-to-test assumption first.
|
|
89
100
|
- Evidence first, then the question. Let the customer reach the conclusion.
|
|
90
101
|
- A brief with zero disproved assumptions wasn't audited - it was accepted.
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
**Enter when:** a significant technical or strategic decision needs to be made, the FDE is asked "what should we do?", the team is stuck between approaches, or a fork in the engagement requires the sponsor's input.
|
|
4
4
|
|
|
5
|
-
**Read first:** `reality.md`, `terrain.md`, `success.md`, `context.md`. Load `business-case.md` if the decision has cost implications.
|
|
5
|
+
**Read first:** `reality.md`, `terrain.md`, `assumptions.md`, `success.md`, `context.md`. Load `business-case.md` if the decision has cost implications.
|
|
6
6
|
|
|
7
7
|
One option is a request for trust. Two options is a false choice. Three options is a conversation between professionals. The FDE who presents three genuine options earns the decision-maker's respect - and their protection when things get hard.
|
|
8
8
|
|
|
@@ -12,24 +12,30 @@ One option is a request for trust. Two options is a false choice. Three options
|
|
|
12
12
|
|
|
13
13
|
> "Decision: approach for the payment migration. Decided by: CTO. Needed by: Friday. Deferral cost: blocks the next sprint and delays the pilot by two weeks."
|
|
14
14
|
|
|
15
|
-
**2. Generate three genuine options.**
|
|
15
|
+
**2. Generate three genuine options from what survived.** Read `assumptions.md` (CONFIRMED / DISPROVED) and `terrain.md` `## Parts`. The playbook is unavailable. Assemble from those blocks only.
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
|-----------------|-------------|-------------|
|
|
19
|
-
| **Conservative** | Lowest risk, smallest change, longest timeline | When trust is thin or the system is fragile |
|
|
20
|
-
| **Pragmatic** | Balanced risk/reward, proven patterns, moderate timeline | When the team is competent and the deadline is real |
|
|
21
|
-
| **Ambitious** | Highest reward, most change, highest risk | When the sponsor has appetite and the team has capacity |
|
|
17
|
+
Not "good / medium / bad." Not three speeds of the same plan (Conservative / Pragmatic / Ambitious of one architecture). Three approaches that differ in **structure** - rearrange the same surviving parts.
|
|
22
18
|
|
|
23
|
-
Each option must be one the FDE would genuinely recommend under different circumstances. If you
|
|
19
|
+
Each option must be one the FDE would genuinely recommend under different circumstances. If you cannot defend an option, replace it - padding is visible.
|
|
20
|
+
|
|
21
|
+
For each option, name:
|
|
22
|
+
- which surviving blocks it is built from
|
|
23
|
+
- which CONVENTION it refuses to obey
|
|
24
|
+
- its single biggest point of failure
|
|
25
|
+
- any new building block, labelled as a new assumption (`UNKNOWN` in `assumptions.md`) - do not smuggle one in as a fact
|
|
26
|
+
|
|
27
|
+
If all three are the same system at different risk levels, you wrote the playbook. Start over.
|
|
24
28
|
|
|
25
29
|
**3. Structure each option identically.** Same dimensions, same format - so comparison is instant:
|
|
26
30
|
|
|
27
31
|
```markdown
|
|
28
|
-
### Option A: <name>
|
|
32
|
+
### Option A: <name>
|
|
33
|
+
- **Blocks:** <which surviving assumptions / parts it is built from>
|
|
34
|
+
- **Convention refused:** <the "we just…" it will not obey>
|
|
29
35
|
- **What:** <the approach in one paragraph>
|
|
30
36
|
- **Timeline:** <estimate with basis>
|
|
31
37
|
- **Cost:** <effort, infrastructure, external>
|
|
32
|
-
- **
|
|
38
|
+
- **Biggest failure:** <the single point that kills this option>
|
|
33
39
|
- **Trade-off:** <what you give up by choosing this>
|
|
34
40
|
- **Best when:** <the condition that makes this the right choice>
|
|
35
41
|
```
|
|
@@ -85,6 +91,7 @@ Recommendation: pragmatic, conditional - *if* Raj is on the design, otherwise sa
|
|
|
85
91
|
## Principles
|
|
86
92
|
|
|
87
93
|
- Three options, never one. One option is a request for trust; three is a real decision.
|
|
94
|
+
- Assemble from surviving blocks. Three speeds of the same plan is the playbook - start over.
|
|
88
95
|
- Each option must be genuinely defensible - no straw men.
|
|
89
96
|
- Same structure for each option. Comparison should take 30 seconds.
|
|
90
97
|
- Recommend one. State why. Accept the override gracefully.
|
package/templates/.fde/README.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
Create with:
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
-
|
|
8
|
+
fde resume --init <engagement-name> # or: npx fdeops resume --init <engagement-name>
|
|
9
9
|
```
|
|
10
10
|
|
|
11
11
|
Stays on **your machine** - not in shared git by default.
|
|
@@ -2,9 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
<!-- Brief claims that are not yet evidence. Land seeds; test-assumptions / discover update. -->
|
|
4
4
|
|
|
5
|
-
| # | Assumption | Blast radius | How we test | Status | Evidence |
|
|
6
|
-
|
|
5
|
+
| # | Assumption | Kind | Blast radius | How we test | Status | Evidence |
|
|
6
|
+
|---|------------|------|--------------|-------------|--------|----------|
|
|
7
7
|
|
|
8
|
+
**Kind:** `FACT` · `CONVENTION` · `UNKNOWN`
|
|
8
9
|
**Blast radius:** `CRITICAL` · `LOAD-BEARING` · `CONVENIENCE`
|
|
9
10
|
**Status:** `OPEN` · `TESTING` · `CONFIRMED` · `DISPROVED` · `PARKED`
|
|
10
11
|
|