fdeops 3.26.0 → 3.27.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.
Files changed (14) hide show
  1. package/README.md +73 -159
  2. package/bin/fde.js +212 -99
  3. package/bin/install.js +1 -1
  4. package/bin/lib/delivery-gaps.js +34 -0
  5. package/bin/lib/provenance.js +42 -0
  6. package/bin/lib/render.js +16 -30
  7. package/bin/lib/value-ledger.js +8 -2
  8. package/mcp/fdeops-ingest/package.json +1 -1
  9. package/package.json +1 -1
  10. package/plugin.json +1 -1
  11. package/skills/fde/SKILL.md +6 -5
  12. package/skills/fde/references/plan.md +2 -0
  13. package/skills/fde/references/poc.md +11 -3
  14. package/skills/fde/references/ship.md +3 -1
package/README.md CHANGED
@@ -1,74 +1,51 @@
1
1
  # FDEOps
2
2
 
3
- **One client record, from first meeting to handover.**
3
+ **The local engagement OS for AI coding agents.**
4
4
 
5
- FDEOps helps a Forward Deployed Engineer or independent expert manage client work with an AI coding agent. Keep the brief, decisions, delivery evidence, acceptance, and next actions together across repositories and sessions.
5
+ FDEOps helps a Forward Deployed Engineer or consultant carry a client engagement from a messy brief to a defensible handover. One `@fde` entry guides the work. A local CLI keeps the record in Markdown; an offline fieldbook shows what needs attention.
6
6
 
7
- One `@fde` skill guides the work. A local CLI records it in Markdown. A read-only dashboard shows one client or your portfolio. You review judgments and obtain customer approval; the tool does not decide for them.
7
+ | When client work goes wrong | What FDEOps helps you keep straight |
8
+ |---|---|
9
+ | The brief describes the wrong problem | What was requested, what you observed, and which assumptions remain untested |
10
+ | Nobody can say who signs | The acceptance owner, approval scope, and unresolved authority |
11
+ | A good number becomes a success claim | What was promised, measured, and accepted, with its source |
12
+ | You switch clients, agents, or engineers | Decisions, constraints, evidence, and one next action in each client's record |
8
13
 
9
- <img width="1536" height="1024" alt="fdeops" src="https://github.com/user-attachments/assets/2bcb8739-55ee-445d-8a1a-8b38433b7b58" />
14
+ You make the judgments and obtain customer approval. The record helps you explain them later.
10
15
 
11
- ---
16
+ <img width="1536" height="1024" alt="fdeops" src="https://github.com/user-attachments/assets/2bcb8739-55ee-445d-8a1a-8b38433b7b58" />
12
17
 
13
18
  ## Quick Start
14
19
 
15
- **Inspect a repository first.** Requires Node.js 18+ and Git. Run from a local repository:
16
-
17
- ```bash
18
- npx fdeops scan
19
- ```
20
-
21
- `npx` may download the package. The scan itself reads local files, prints reconnaissance and questions, and does not write engagement records.
22
-
23
- **Then install the skill:**
20
+ Requires Node.js 18+, Git, and an AI coding agent for the guided workflow. `npx` may download packages; the FDEOps CLI operates locally.
24
21
 
25
22
  ```bash
26
23
  npx skills add suboss87/fdeops --skill fde
27
24
  ```
28
25
 
29
- One chat. Name the client:
26
+ Open the client workspace and tell your agent:
30
27
 
31
28
  ```text
32
29
  @fde this is client01
33
30
  ```
34
31
 
35
- The agent creates and binds `~/fde-engagements/client01/.fde/` to the workspace. Paste kickoff notes; review the proposed decisions, risks, and next actions before saving. If setup cannot run in your host, use `npx fdeops resume --init client01` to create the engagement and binding.
32
+ The agent creates `~/fde-engagements/client01/.fde/` and binds the workspace to it. If the host cannot run setup, use `npx fdeops resume --init client01` to create the engagement and binding.
36
33
 
37
- Open the engagement fieldbook anytime:
38
-
39
- ```bash
40
- npx fdeops dashboard --open
41
- ```
42
-
43
- Read-only HTML of the record - promised, measured, accepted, and evidence. Regenerate after you change memory. Day to day: [docs/USAGE.md](docs/USAGE.md).
34
+ **Try the record before using client data:** `npx fdeops demo` runs a fictional notes-to-fieldbook workflow without a model. It writes under `~/fde-engagements/.demo/` and resets that sandbox each run. Remove it with `npx fdeops demo --clean`. For repository reconnaissance without writing engagement records, use `npx fdeops scan`.
44
35
 
45
36
  <details>
46
- <summary><b>Claude Code</b></summary>
37
+ <summary>Host installation and offline use</summary>
38
+
39
+ Claude Code plugin:
47
40
 
48
41
  ```text
49
42
  /plugin marketplace add suboss87/fdeops
50
43
  /plugin install fdeops@fdeops
51
44
  ```
52
45
 
53
- The plugin registers Claude Code session hooks and slash commands. A skill-only install does not register hooks.
54
-
55
- </details>
46
+ The plugin registers session hooks and slash commands. Skill-only installations do not register those hooks. For Cursor, Codex, Gemini, or Copilot, install the skill and run `npx fdeops adapters .` in the client workspace; this writes instruction pointers.
56
47
 
57
- <details>
58
- <summary><b>Cursor</b></summary>
59
-
60
- After the skill install, in the **client repo** you have open (pointer, not a second pack):
61
-
62
- ```bash
63
- npx fdeops adapters .
64
- ```
65
-
66
- See [adapters/](adapters/README.md).
67
-
68
- </details>
69
-
70
- <details>
71
- <summary><b>Clone install and offline use</b></summary>
48
+ Clone installation:
72
49
 
73
50
  ```bash
74
51
  git clone https://github.com/suboss87/fdeops.git
@@ -76,169 +53,106 @@ cd fdeops
76
53
  node bin/install.js
77
54
  ```
78
55
 
79
- If the agent cannot create the folder:
80
-
81
- ```bash
82
- npx fdeops resume --init client01 # ~/fde-engagements/client01
83
- ```
84
-
85
- For offline use, transfer the checkout first; cloning and package downloads need network access. Override: `FDEOPS_ENGAGEMENT`. See [docs/install.md](docs/install.md).
56
+ Offline machines need an already-transferred checkout, Node.js, and Git. Advanced override: `FDEOPS_ENGAGEMENT`. See [installation](docs/install.md) and [host adapters](adapters/README.md).
86
57
 
87
58
  </details>
88
59
 
89
- ---
90
-
91
60
  ## Commands
92
61
 
93
- One command per stage. Skills load automatically.
94
-
95
- Six stages organize the engagement: Land, Discover, Plan, Ship, Outcome, Close. Start with the current situation; revisit earlier decisions when the evidence changes. Slash commands below are provided by the Claude Code plugin. In other hosts, describe the same request to `@fde`.
62
+ One command per stage. Skills load automatically. Describe the situation to `@fde`; the Claude Code plugin also provides these slash commands.
96
63
 
97
- | What you're doing | Command | Stage |
98
- |-------------------|---------|-------|
99
- | First days. Get the brief. Name who signs. | `/brief` | Land |
100
- | Check the brief is the real job. | `/discover` | Discover |
101
- | Sequence from done, not from the ticket. | `/plan` | Plan |
102
- | Prove it on their staging, then go live. | `/ship` | Ship |
103
- | What you promised, measured, and who accepted. | `/outcome` | Outcome |
104
- | Hand it over. They run it without you. | `/close` | Close |
64
+ | Stage | Command | Result to review |
65
+ |---|---|---|
66
+ | Land | `/brief` | The brief, unknowns, and who can accept the work |
67
+ | Discover | `/discover` | The actual workflow and evidence behind the problem |
68
+ | Plan | `/plan` | A small deliverable, constraints, and acceptance criteria |
69
+ | Ship | `/ship` | Proof on their staging, release approval, and rollback |
70
+ | Outcome | `/outcome` | Promised, measured, accepted, and supporting evidence |
71
+ | Close | `/close` | Runbook, operating owner, and handover gaps |
105
72
 
106
- 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).
73
+ Daily requests: `/debrief`, `/prep`, `/receipts`, `/readout`, and `/trust`. Revisit earlier stages when evidence changes; a new incident does not require restarting discovery.
107
74
 
108
- You can also describe the situation in plain English: a new client, a POC, an incident, a scope change, or a question about what was agreed.
75
+ ## One loop you can defend
109
76
 
110
- ---
77
+ Paste messy notes after a meeting:
111
78
 
112
- ## Your daily fieldbook
79
+ ```text
80
+ @fde Debrief: Mara agreed to CSV upload. Devon asked for ERP sync,
81
+ but Mara has not approved it. The staging replay took 5 minutes;
82
+ we have no comparable production baseline. Ask Mara for staging access.
83
+ ```
113
84
 
114
- ![FDEOps dark dashboard showing next actions and attention gaps across three fictional clients](media/fieldbook-preview.png)
85
+ 1. **Review:** the agent separates decisions, requests, unknowns, measurements, and next actions. Check the source and any conflicts with existing records.
86
+ 2. **Apply:** confirm the proposed interpretation. An ERP request stays a request; a staging result stays a staging result. Saving the record does not mean the customer approved either.
87
+ 3. **Defend:** ask `@fde What did we agree about ERP, and what evidence supports the result?` Review the supplied source, superseded decisions, and missing evidence before using the answer in a sponsor update.
115
88
 
116
- *Fictional client records, shown in the built-in dark theme. The report works offline.*
89
+ The CLI supports this loop with `debrief --smart`, reviewed `--apply`, `recall`, `receipts`, and `defend`. `fde handoff --out successor.md` creates a new portable, redacted packet. See the [walkthrough](docs/USAGE.md) for examples. Direct CLI write commands execute when invoked; enabled session hooks automatically capture mechanical session state. Agent judgments still need review.
117
90
 
118
- Read [verification results and limits](docs/verification.md) for context measurements, local-model observations, and MCP coverage.
91
+ ## Your daily fieldbook
119
92
 
120
- Open `npx fdeops dashboard --all --open` to review every client. Filter what needs attention, open a client, and copy **Continue next action** into your agent. After a meeting, use **Debrief notes**; before a sponsor update, use **Review outcome**. These buttons copy prompts; work runs in your agent. Review changes there and regenerate the dashboard afterward.
93
+ ![FDEOps dark dashboard showing next actions and attention gaps across three fictional clients](media/fieldbook-preview.png)
121
94
 
122
- ## Try the complete loop
95
+ *Fictional client records in the built-in dark theme. The report works offline.*
123
96
 
124
97
  ```bash
125
- npx fdeops demo
98
+ npx fdeops dashboard --open # this client
99
+ npx fdeops dashboard --all --open # all clients
126
100
  ```
127
101
 
128
- This writes fictional records and HTML under `~/fde-engagements/.demo/`, resetting its own sandbox on each run. It requires no AI account. Open the generated report; remove the demo later with `npx fdeops demo --clean`. Follow the [five-minute walkthrough](docs/USAGE.md#new-here-5-minutes) for what to inspect.
129
-
130
-
131
- ---
132
-
133
- ## All 30 Skills
134
-
135
- Not prompts to choose from: the router loads one relevant skill with concrete steps, an artifact, and a checkpoint. The [skills reference](docs/skills-reference.md) lists all 30, from discovery and scope control to incident response and handover. Industry and AI overlays apply when relevant.
136
-
137
- Optional external sources use your configured MCP connections. The agent pulls on request, stages the material, and asks you to review its interpretation before applying it. The CLI itself stays local. See [source recipes](mcp/recipes/) and [ingest usage](docs/USAGE.md#ingest-pull-large-artifacts--same-confirm-loop).
138
-
139
- ---
102
+ Filter what needs attention, open a client, and copy **Continue next action**, **Debrief notes**, or **Review outcome** into your agent. The fieldbook is a read-only snapshot: work happens in your agent or CLI, then you regenerate the report. Review confidential information before sharing it with a sponsor or incoming engineer.
140
103
 
141
104
  ## How Skills Work
142
105
 
143
- One `@fde`. One file per situation. One folder per client.
106
+ One entry, one source of methodology, one record per client:
144
107
 
108
+ ```text
109
+ @fde + your situation → one relevant skill → reviewed work → .fde/ → fieldbook
145
110
  ```
146
- "@fde this is client01" creates ~/fde-engagements/client01/.fde/
147
- /brief or English the AI coding agent loads skills/fde/SKILL.md
148
- │ routes. you never pick a skill by name
149
- ▼
150
- references/<one>.md one skill, then stop
151
- │
152
- ▼
153
- fde CLI (local) dates, gates, redacts. no network
154
- │ after you confirm
155
- ▼
156
- ~/fde-engagements/client01/.fde/
157
- │
158
- ▼
159
- fde dashboard --open offline fieldbook (read-only snapshot)
160
- ```
161
-
162
- **A dated line, or it did not happen.** Promised → measured → accepted, with evidence for the measurement. If it is not in `.fde/`, it is not on the record.
163
111
 
164
- **Review judgments before recording them.** The agent shows proposed interpretations for confirmation. Direct CLI writes execute when invoked; enabled session hooks also capture mechanical session state automatically. Recording a note does not establish customer approval.
112
+ **All 30 skills:** Not prompts to choose from. Each reference contains steps, an artifact, and a checkpoint. The [skills guide](docs/skills.md) has three short checklists for day zero, discovery to a small ship, and POC to production. The [full reference](docs/skills-reference.md) covers all stages and overlays.
165
113
 
166
- **The record is on your laptop.** Change hosts and keep the same Markdown. Claude Code plugins provide automatic session hooks; other hosts use `@fde` and CLI commands on demand. See the [install matrix](docs/install.md#who-needs-which-install).
167
-
168
- 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).
169
-
170
- ---
114
+ Optional external sources use MCP connections configured in your agent host. Pull material on request, review its interpretation, then apply it. The CLI does not connect to those services. See [source recipes](mcp/recipes/).
171
115
 
172
116
  ## Engagement memory (`.fde/`)
173
117
 
174
- One folder per client. Plain markdown. Grep it, copy it, take it into a meeting.
175
-
176
- | File | Holds |
177
- |------|-------|
178
- | `context.md` | Where you are |
179
- | `brief.md` / `success.md` | What they asked; what “done” is and who signs |
180
- | `reality.md` / `terrain.md` | The real problem; the map |
181
- | `stakeholders.md` | `[signal:green\|amber\|red]` - worst active signal wins; empty is **new**, not green |
182
- | `trust-profile.md` | Sacred data, AI policy, approval chain |
183
- | `decisions.md` / `risks.md` / `delivery.md` | Dated choices; live risks; what shipped, evidence, rollback, acceptance |
184
-
185
- Schema: [docs/schema.md](docs/schema.md). Fieldbook: `npx fdeops dashboard --open` (bound) or `--all --open` (portfolio).
118
+ | Record | What it preserves |
119
+ |---|---|
120
+ | `context.md` | Current state and next action |
121
+ | `brief.md`, `reality.md`, `terrain.md` | Request, observed problem, and system constraints |
122
+ | `success.md`, `stakeholders.md`, `trust-profile.md` | Acceptance criteria, people, data policy, and authority |
123
+ | `decisions.md`, `risks.md`, `delivery.md` | Choices, unresolved risks, measurements, evidence, and recorded acceptance |
186
124
 
187
- ---
125
+ Markdown stays on your machine when you change hosts. Bounded `resume` and topic-based `recall` reduce what enters the active context; omitted history still needs retrieval. See the [record schema](docs/schema.md) and [verification results](docs/verification.md). Passing software tests does not establish reliable judgment from every model.
188
126
 
189
127
  ## Who this is for
190
128
 
191
- Forward Deployed Engineers, independent consultants, and solo agencies delivering inside customer systems. Use a separate engagement folder for each client and a workspace binding to select the right record.
129
+ FDEs, independent consultants, and solo agencies working inside customer systems. Sponsors and incoming engineers can review the resulting records and reports without learning the skill catalog. FDEOps supports delivery decisions; it does not replace customer authority or operate their infrastructure for you.
192
130
 
193
- 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.
131
+ ## Principles
194
132
 
195
- ---
133
+ - Verify the brief before building; keep unknowns explicit.
134
+ - Name who can accept which outcome.
135
+ - Keep promised, measured, and accepted results separate.
136
+ - Prove a small change where the client will operate it, with a tested recovery path.
137
+ - Leave a record another engineer can understand and challenge.
138
+ - Keep each client separate and confirm the active binding before writing.
196
139
 
197
140
  ## Your data stays yours
198
141
 
199
- 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. Keep the engagement folder outside cloud-sync locations unless customer policy permits that storage. Generated reports can still contain confidential information after redaction; review them before sharing.
142
+ The CLI uses local files and Git, with no network or telemetry. Your AI host may send the material it reads to its configured model. CLI, hook, and fieldbook outputs redact `<private>` blocks; do not paste or load raw private blocks with file tools. Follow customer storage policy and review reports before sharing.
200
143
 
201
- [PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
202
-
203
- ---
204
-
205
- ## Principles
206
-
207
- - **Who signs** - name them in the first days
208
- - **Brief vs real job** - check the floor, not only the slide
209
- - **Back from done** - sequence from signed-off, not from the ticket
210
- - **Their staging then live** - prove it where they operate, then go live
211
- - **Promised, measured, accepted** - a number nobody signed is claimed, not delivered; keep the evidence
212
- - **They run it** - if they cannot operate it without you, you are not done
213
- - **A dated line, or it did not happen** - these files get defended in the room
214
- - **One customer, one folder** - verify the active binding before writing
215
- - **The kit says what to check. You still decide.**
216
-
217
- ---
144
+ [Privacy](PRIVACY.md) · [Security](SECURITY.md)
218
145
 
219
146
  ## Project Structure
220
147
 
221
- | Folder | Responsibility |
222
- |---|---|
223
- | `skills/fde/` | One router and the delivery methodology |
224
- | `bin/` | Local CLI, installer, and shared helpers |
225
- | `templates/.fde/` | Client record templates |
226
- | `adapters/` and `hooks/` | Host entry points and session integration |
227
- | `mcp/` | Optional ingest wrapper and source recipes |
228
- | `test/` and `evals/` | Code regressions and workflow evaluations |
229
- | `docs/` and `examples/` | Usage, contributor guides, and fictional engagements |
230
-
231
- See [repository layout](docs/REPO_LAYOUT.md) for where to make changes.
232
-
233
-
234
- ---
148
+ Methodology lives in `skills/fde/`; deterministic commands and shared helpers in `bin/`; host entry points in `adapters/` and `hooks/`. `templates/`, `test/`, `evals/`, and `examples/` support the same workflow. The [repository map and documentation index](docs/REPO_LAYOUT.md) explain where to start and where changes belong.
235
149
 
236
150
  ## Contributing
237
151
 
238
- **[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)
152
+ Maintained by **[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. Share an anonymized failure case, a reproducible bug, or a focused improvement through [Issues](https://github.com/suboss87/fdeops/issues) or [Discussions](https://github.com/suboss87/fdeops/discussions).
239
153
 
240
- Skills should be **specific** (actionable steps), **verifiable** (an artifact in `.fde/`), and **minimal**. The `fde` CLI stays local-only.
154
+ [Contribution guide](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md)
241
155
 
242
156
  ## License
243
157
 
244
- MIT - use these skills on client work.
158
+ MIT - use FDEOps on client work. Preserve applicable license notices when redistributing.