fdeops 3.24.0 → 3.26.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 (16) hide show
  1. package/README.md +129 -181
  2. package/adapters/LOCAL-LLM.md +14 -102
  3. package/bin/check.js +3 -3
  4. package/bin/fde.js +310 -281
  5. package/bin/install.js +73 -50
  6. package/bin/lib/context.js +85 -0
  7. package/bin/lib/fieldbook-client.js +41 -10
  8. package/bin/lib/font-css.js +115 -0
  9. package/bin/lib/install-paths.js +53 -0
  10. package/bin/lib/render.js +41 -44
  11. package/bin/lib/value-ledger.js +34 -0
  12. package/hooks/session-start +18 -84
  13. package/mcp/fdeops-ingest/package.json +1 -1
  14. package/package.json +2 -2
  15. package/plugin.json +1 -1
  16. package/skills/fde/SKILL.md +1 -1
package/README.md CHANGED
@@ -1,123 +1,74 @@
1
1
  # FDEOps
2
2
 
3
- **Turn a customer request into the smallest useful delivery - and keep the evidence that it worked.**
3
+ **One client record, from first meeting to handover.**
4
4
 
5
- FDEOps gives your AI coding agent a method for customer delivery: investigate the request, agree what success means, carry decisions into implementation, and prepare a handoff the customer can operate.
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.
6
6
 
7
- One `@fde` skill routes 30 field situations. A local CLI keeps dated records in a separate folder for each customer. An offline fieldbook makes those records easy to review before the next meeting.
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.
8
8
 
9
- Keep your existing coding skills. FDEOps supplies the customer context, scope, approvals, and acceptance criteria around their engineering work.
9
+ <img width="1536" height="1024" alt="fdeops" src="https://github.com/user-attachments/assets/2bcb8739-55ee-445d-8a1a-8b38433b7b58" />
10
10
 
11
- [Quick start](#quick-start) · [Daily workflow](#your-daily-workflow) · [30 skills](#all-30-skills) · [Usage guide](docs/USAGE.md) · [Install options](docs/install.md)
12
-
13
- ## What you get
14
-
15
- | Start with | Work with your agent toward | Keep on the record |
16
- |---|---|---|
17
- | A customer request and an unfamiliar repository | An evidence-backed problem statement and the smallest useful increment | Brief, constraints, open questions, success criteria |
18
- | Meeting notes and changing requirements | Reviewed decisions, owners, scope changes, and next actions | Dated customer-specific memory |
19
- | A shipped change | A readout that distinguishes promised, measured, and accepted results | Delivery evidence, acceptance status, operating handoff |
20
-
21
- For example: a customer asks for an AI reconciliation agent by Friday. FDEOps guides your agent to inspect the existing workflow, distinguish the requested solution from the underlying problem, and establish a baseline and acceptance owner. An existing integration may be enough. The evidence should determine the plan.
22
-
23
- This is a workflow you carry out with your agent; the CLI does not diagnose a repository or validate customer outcomes by itself.
24
-
25
- ## Commands
26
-
27
- One command per stage. Skills load automatically through `@fde`.
28
-
29
- Use natural language with `@fde` in any supported host. The Claude Code plugin also provides these slash commands. The lifecycle is **Land → Discover → Plan → Ship → Outcome → Close**; your agent routes the situation to the relevant step.
30
-
31
- | What you need | Command | Stage |
32
- |---|---|---|
33
- | Establish the brief and who accepts success | `/brief` | Land |
34
- | Check the problem against the actual workflow | `/discover` | Discover |
35
- | Sequence the smallest useful delivery from acceptance backward | `/plan` | Plan |
36
- | Verify on customer staging and prepare the approved release | `/ship` | Ship |
37
- | Separate promised, measured, and accepted results | `/outcome` | Outcome |
38
- | Transfer operations and confirm the handoff | `/close` | Close |
39
-
40
- For recurring work: `/debrief`, `/prep`, `/trust`, `/receipts`, and `/readout`. A sponsor readout is an Outcome workflow, not an additional lifecycle stage.
11
+ ---
41
12
 
42
13
  ## Quick Start
43
14
 
44
- Requires **Node.js 18+** and Git for versioned engagement memory. Install on your own machine, where you run your coding agent.
45
-
46
- ### 1. See the workflow with fictional data
15
+ **Inspect a repository first.** Requires Node.js 18+ and Git. Run from a local repository:
47
16
 
48
17
  ```bash
49
- npx fdeops demo
18
+ npx fdeops scan
50
19
  ```
51
20
 
52
- The demo creates a fictional Acme payments engagement, reviews and applies sample notes, retrieves a dated decision, prepares a meeting brief, and generates an HTML fieldbook. Open the file path printed at the end.
53
-
54
- It runs real local commands in `~/fde-engagements/.demo/`. Re-running resets that demo; `npx fdeops demo --clean` removes it. Your real engagements are separate. No AI account is required for this CLI walkthrough. The first `npx` invocation may download the package; the CLI itself makes no network requests.
55
-
56
- Want repository reconnaissance first? Run `npx fdeops scan` in a repository. It reads local files and Git state, prints findings and questions, and writes nothing.
21
+ `npx` may download the package. The scan itself reads local files, prints reconnaissance and questions, and does not write engagement records.
57
22
 
58
- ### 2. Install the agent skill
23
+ **Then install the skill:**
59
24
 
60
25
  ```bash
61
26
  npx skills add suboss87/fdeops --skill fde
62
27
  ```
63
28
 
64
- In your coding agent, with the customer workspace open:
29
+ One chat. Name the client:
65
30
 
66
31
  ```text
67
- @fde this is client01. The customer wants to reduce manual order
68
- reconciliation. Inspect the relevant workflow before asking questions.
69
- Help me define the smallest useful increment and how we will prove it worked.
32
+ @fde this is client01
70
33
  ```
71
34
 
72
- Your agent sets up `~/fde-engagements/client01/.fde/` and binds the workspace to that engagement. It routes to the relevant skill, investigates the available context, and reviews judgment-based changes with you. Unknown baselines and approvals should remain unknown until confirmed.
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.
73
36
 
74
- If setup needs a terminal fallback, run `npx fdeops resume --init client01` from the customer workspace. This creates the engagement record and binds that workspace; running it with another client replaces the binding.
75
-
76
- ### 3. Start the daily loop
77
-
78
- ```text
79
- @fde Debrief: <meeting notes>
80
- @fde Prep me for the next customer meeting.
81
- @fde Draft a readout. Separate what we promised, measured, and the customer accepted.
82
- ```
83
-
84
- Open your engagement's fieldbook:
37
+ Open the engagement fieldbook anytime:
85
38
 
86
39
  ```bash
87
40
  npx fdeops dashboard --open
88
41
  ```
89
42
 
90
- Continue with the [five-minute walkthrough and daily guide](docs/USAGE.md).
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).
91
44
 
92
45
  <details>
93
- <summary><b>Claude Code plugin</b></summary>
46
+ <summary><b>Claude Code</b></summary>
94
47
 
95
48
  ```text
96
49
  /plugin marketplace add suboss87/fdeops
97
50
  /plugin install fdeops@fdeops
98
51
  ```
99
52
 
100
- Includes slash commands and session hooks. The plugin does not add a bare `fde` command to your shell; use `npx fdeops <command>` or install the CLI globally. [Install details](docs/install.md).
53
+ The plugin registers Claude Code session hooks and slash commands. A skill-only install does not register hooks.
101
54
 
102
55
  </details>
103
56
 
104
57
  <details>
105
- <summary><b>Cursor, Codex, Gemini CLI, and Copilot</b></summary>
58
+ <summary><b>Cursor</b></summary>
106
59
 
107
- After installing the skill, run this in the customer workspace to add host pointers:
60
+ After the skill install, in the **client repo** you have open (pointer, not a second pack):
108
61
 
109
62
  ```bash
110
63
  npx fdeops adapters .
111
64
  ```
112
65
 
113
- Adapters point at the same skill rather than copying its method. This command adds instruction files to the workspace; review them as you would other repository changes. Session hooks are Claude Code-first; other hosts use the skill and CLI on demand. [Adapters](adapters/README.md).
66
+ See [adapters/](adapters/README.md).
114
67
 
115
68
  </details>
116
69
 
117
70
  <details>
118
- <summary><b>Install from a checkout / offline preparation</b></summary>
119
-
120
- On a connected machine:
71
+ <summary><b>Clone install and offline use</b></summary>
121
72
 
122
73
  ```bash
123
74
  git clone https://github.com/suboss87/fdeops.git
@@ -125,172 +76,169 @@ cd fdeops
125
76
  node bin/install.js
126
77
  ```
127
78
 
128
- For an offline machine, transfer the checkout first, then run `node bin/install.js` there. The installer copies the skill and hooks into your local Claude directories. [Install options and overrides](docs/install.md).
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).
129
86
 
130
87
  </details>
131
88
 
132
- ## Your daily workflow
89
+ ---
133
90
 
134
- | When | In your agent | In the fieldbook |
135
- |---|---|---|
136
- | Start the day | `@fde Where did we leave off with this client?` | Review the next action, risks, and gaps needing attention |
137
- | Before a meeting | `@fde Prep me for the sponsor check-in.` | Review the brief, stakeholders, and recent decisions |
138
- | After a meeting | `@fde Debrief: <notes>` | Regenerate after reviewing and applying the changes |
139
- | Before reporting value | `@fde Draft the customer readout with evidence and unresolved gaps.` | Check the promised → measured → accepted ledger |
91
+ ## Commands
140
92
 
141
- `npx fdeops dashboard --all --open` shows every engagement. The fieldbook is a **read-only snapshot**, with search, engagement views, and prompts you can copy into your agent for follow-up work. It does not run the agent or edit memory. Regenerate it after changing the record; the generation date tells you how fresh it is.
93
+ One command per stage. Skills load automatically.
142
94
 
143
- ## All 30 Skills
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`.
96
+
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 |
144
105
 
145
- 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.
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).
146
107
 
147
- Full detail: [docs/skills-reference.md](docs/skills-reference.md).
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.
148
109
 
149
- ### Land
110
+ ---
150
111
 
151
- | Skill | What it does | Use when |
152
- |--------|--------------|----------|
153
- | [land](skills/fde/references/land.md) | Interrogate the brief | New client, first meeting, just got the brief |
154
- | [audit](skills/fde/references/audit.md) | Verify inherited claims | Taking over, previous consultant left |
155
- | [who-decides](skills/fde/references/who-decides.md) | Map decision rights | Need to know who matters |
156
- | [earn-trust](skills/fde/references/earn-trust.md) | Earn access | Need access or credibility |
157
- | [hold-scope](skills/fde/references/hold-scope.md) | Hold scope | "Also can you…", timeline unchanged |
112
+ ## Your daily fieldbook
158
113
 
159
- ### Discover
114
+ ![FDEOps dark dashboard showing next actions and attention gaps across three fictional clients](media/fieldbook-preview.png)
160
115
 
161
- | Skill | What it does | Use when |
162
- |--------|--------------|----------|
163
- | [discover](skills/fde/references/discover.md) | Frame the problem | Brief feels wrong, shadow processes |
164
- | [test-assumptions](skills/fde/references/test-assumptions.md) | Test assumptions | Brief feels too neat |
165
- | [score-use-cases](skills/fde/references/score-use-cases.md) | Score use cases | Everything is P0 |
166
- | [poc](skills/fde/references/poc.md) | Validate the solution | POC, spike, need to de-risk |
116
+ *Fictional client records, shown in the built-in dark theme. The report works offline.*
167
117
 
168
- ### Plan
118
+ Read [verification results and limits](docs/verification.md) for context measurements, local-model observations, and MCP coverage.
169
119
 
170
- | Skill | What it does | Use when |
171
- |--------|--------------|----------|
172
- | [plan](skills/fde/references/plan.md) | Sequence the work | What order, what is done |
173
- | [business-case](skills/fde/references/business-case.md) | Build the business case | Defend budget or timeline |
174
- | [three-options](skills/fde/references/three-options.md) | Generate options | "What should we do?" |
175
- | [pick-three](skills/fde/references/pick-three.md) | Prioritize three | Everything is urgent |
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.
176
121
 
177
- ### Ship
122
+ ## Try the complete loop
178
123
 
179
- | Skill | What it does | Use when |
180
- |--------|--------------|----------|
181
- | [ship](skills/fde/references/ship.md) | Deliver the increment | Building, updating, or going live |
182
- | [what-breaks](skills/fde/references/what-breaks.md) | Assess impact | Touching shared infrastructure |
183
- | [rescue](skills/fde/references/rescue.md) | Resolve the incident | Down, or they went quiet |
184
- | [review](skills/fde/references/review.md) | Review the change | Before merge, scope creep |
185
- | [rollback](skills/fde/references/rollback.md) | Rehearse rollback | "We can always revert" |
124
+ ```bash
125
+ npx fdeops demo
126
+ ```
186
127
 
187
- ### Outcome
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.
188
129
 
189
- | Skill | What it does | Use when |
190
- |--------|--------------|----------|
191
- | [readout](skills/fde/references/readout.md) | Report the outcome | Friday, sponsor update |
192
- | [demo-prep](skills/fde/references/demo-prep.md) | Prepare the demo | Demo or exec walkthrough |
193
- | [debrief](skills/fde/references/debrief.md) | Capture the meeting | Just left a meeting |
194
- | [board-memo](skills/fde/references/board-memo.md) | Brief the board | Justify continued investment |
195
- | [dashboard](skills/fde/references/dashboard.md) | View the portfolio | All my customers |
196
- | [ingest](skills/fde/references/ingest.md) | Ingest sources | Transcript, Notion, Slack |
197
- | [connect](skills/fde/references/connect.md) | Connect a source | Connect Granola |
198
130
 
199
- ### Close
131
+ ---
200
132
 
201
- | Skill | What it does | Use when |
202
- |--------|--------------|----------|
203
- | [close](skills/fde/references/close.md) | Transfer operations | Wrapping up |
204
- | [runbook](skills/fde/references/runbook.md) | Write the runbook | They must operate without you |
205
- | [switch-clients](skills/fde/references/switch-clients.md) | Switch engagements | 2+ clients |
206
- | [encode-pattern](skills/fde/references/encode-pattern.md) | Encode the pattern | It will apply again |
207
- | [red-team](skills/fde/references/red-team.md) | Challenge the plan | "Poke holes in this" |
133
+ ## All 30 Skills
208
134
 
209
- 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).
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.
210
136
 
211
- Optional pull: you add the source MCP; we **pull** on request. [mcp/recipes/](mcp/recipes/)
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).
212
138
 
213
139
  ---
214
140
 
215
141
  ## How Skills Work
216
142
 
217
- ```text
218
- Customer request + repository + available notes
219
- ↓
220
- @fde → one relevant reference → investigation and proposed next step
221
- ↓
222
- You review judgment, scope, and commitments
223
- ↓
224
- Local CLI + customer-specific .fde/ records
225
- ↓
226
- Meeting prep · dated receipts · offline fieldbook · customer readout
143
+ One `@fde`. One file per situation. One folder per client.
144
+
145
+ ```
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)
227
160
  ```
228
161
 
229
- The method lives once in [`skills/fde/SKILL.md`](skills/fde/SKILL.md) and its references. Adapters point to it. The CLI handles deterministic file operations, dates, gates, and output redaction. Your coding agent supplies interpretation; you retain responsibility for decisions and customer approval.
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.
230
163
 
231
- Agent-proposed judgments are reviewed before they enter the record. Setup, explicitly invoked CLI writes, and configured session hooks can write local files without a separate chat confirmation. [Operating rules](docs/OPERATIONS.md).
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.
232
165
 
233
- ## Engagement memory (`.fde/`)
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).
234
167
 
235
- One folder per client, stored by default at `~/fde-engagements/<client>/.fde/`. Plain Markdown and local Git history keep the record portable across supported agent hosts.
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).
236
169
 
237
- | File | What it answers |
238
- |---|---|
239
- | `context.md` | Where are we, and what happens next? |
240
- | `brief.md` / `success.md` | What did the customer request; what counts as success; who accepts it? |
241
- | `reality.md` / `terrain.md` | What did investigation reveal? |
242
- | `stakeholders.md` / `trust-profile.md` | Who is involved; what access and approval constraints apply? |
243
- | `decisions.md` / `risks.md` | What changed, why, and what could block delivery? |
244
- | `delivery.md` | What shipped; what evidence, rollback, and acceptance were recorded? |
170
+ ---
245
171
 
246
- Memory stores what you recorded. A dated note is evidence of that record, not independent proof that a result occurred or that a customer approved it. Keep supporting sources and explicit uncertainty with the claim.
172
+ ## Engagement memory (`.fde/`)
247
173
 
248
- Use `FDEOPS_ENGAGEMENTS_ROOT` to change the storage root or `FDEOPS_ENGAGEMENT` for an explicit engagement override. See [install options](docs/install.md#advanced-engagement-overrides).
174
+ One folder per client. Plain markdown. Grep it, copy it, take it into a meeting.
249
175
 
250
- [Memory schema](docs/schema.md) · [Multi-client usage](docs/USAGE.md#multiple-engagements)
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 |
251
184
 
252
- ## Principles
185
+ Schema: [docs/schema.md](docs/schema.md). Fieldbook: `npx fdeops dashboard --open` (bound) or `--all --open` (portfolio).
253
186
 
254
- - Investigate the actual workflow before committing to a solution.
255
- - Define a small useful increment, a success criterion, and an acceptance owner.
256
- - Keep observations, assumptions, and customer decisions distinguishable.
257
- - Verify the result in the customer environment and preserve its evidence.
258
- - Separate promised, measured, and accepted outcomes.
259
- - Hand over something the customer can operate; keep each customer's record separate.
187
+ ---
260
188
 
261
189
  ## Who this is for
262
190
 
263
- Forward deployed engineers, technical consultants, and solutions engineers working with a customer team that must accept and operate the result. Especially useful when you return across sessions or switch between several engagements.
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.
264
192
 
265
- FDEOps adds customer-delivery workflows to your existing coding tools. It does not replace code review, engineering tests, customer relationships, or your organization's release process. It does not provide hosted synchronization or a CRM.
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.
194
+
195
+ ---
266
196
 
267
197
  ## Your data stays yours
268
198
 
269
- - **CLI:** local Git and file operations; no network requests or telemetry. Package installation can require network access.
270
- - **Agent:** your chosen host model sees the context and code you give it. Local storage does not make a cloud-hosted model local.
271
- - **Private notes:** `<private>` blocks are redacted from CLI, dashboard, and hook outputs. Do not open raw private blocks with agent file tools or paste them into chat.
272
- - **Storage:** customer records live outside the customer repository by default. Keep the engagement folder out of shared Git and cloud-synced folders unless your customer policy permits them.
273
- - **Integrations:** optional source MCPs pull on request through your host. They have their own permissions and data boundaries; the CLI does not push to external services.
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.
274
200
 
275
201
  [PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
276
202
 
277
- ## Quality and contributing
203
+ ---
278
204
 
279
- The repository includes deterministic CLI tests, structural checks, and skill-routing evaluations. These verify defined behaviors; they are not a claim of measured customer productivity or fully autonomous delivery.
205
+ ## Principles
280
206
 
281
- From a checkout:
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.**
282
216
 
283
- ```bash
284
- npm run check
285
- npm run test:skill-routing
286
- ```
217
+ ---
218
+
219
+ ## Project Structure
220
+
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
+ ---
287
235
 
288
- Live routing evaluation depends on the configured provider; inspect the output for skipped live checks. See [`evals/`](evals/) for scenarios and [`docs/REPO_LAYOUT.md`](docs/REPO_LAYOUT.md) for the code layout.
236
+ ## Contributing
289
237
 
290
- Maintained by **[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. Share bugs and anonymized field situations through [Issues](https://github.com/suboss87/fdeops/issues) or [Discussions](https://github.com/suboss87/fdeops/discussions). Keep customer data out of contributions.
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)
291
239
 
292
- [CONTRIBUTING.md](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md)
240
+ Skills should be **specific** (actionable steps), **verifiable** (an artifact in `.fde/`), and **minimal**. The `fde` CLI stays local-only.
293
241
 
294
242
  ## License
295
243
 
296
- [MIT](LICENSE) - use these skills on client work.
244
+ MIT - use these skills on client work.
package/adapters/LOCAL-LLM.md CHANGED
@@ -1,110 +1,22 @@
1
- # fdeops - Local LLM Setup
1
+ # Local models
2
2
 
3
- Use fdeops with **any local model** - Ollama, LM Studio, llama.cpp, vLLM, Open WebUI, or any inference server that accepts a system prompt.
3
+ The FDEOps CLI and offline dashboard need Node.js and Git, not a model. AI-assisted work additionally needs a local model **and an agent host that can read files and run approved CLI commands**. A chat box with the skill pasted into its system prompt does not automatically gain those capabilities.
4
4
 
5
- ## Why it works
5
+ ## Use your existing local agent
6
6
 
7
- fdeops is a SKILL.md file + markdown memory + a Node.js CLI. It calls no external API. The AI does the skills; the CLI does the mechanics. Any model that can read a markdown system prompt can run fdeops.
7
+ 1. Download FDEOps, your agent host and your model while online. After that, the CLI operates offline. Model/provider configuration belongs to the host; FDEOps does not start or configure an inference server.
8
+ 2. From the client workspace, run `node /path/to/fdeops/bin/fde.js resume --init my-client` to create and bind a local record.
9
+ 3. Make `skills/fde/SKILL.md` and its references available to the host. Use the host's documented skill/file mechanism. Give it the FDEOps CLI path and permission to read the bound record and execute the requested commands.
10
+ 4. Start with `fde resume` and ask for the next action. Inspect the tool calls, cited records and any proposed writes before trusting the workflow.
8
11
 
9
- ## Setup
12
+ Use `fde recall <topic>` for relevant evidence. `resume` and `recall` default to a 16 KiB output ceiling; `--max-bytes 4096` requests a smaller allowance. This limits FDEOps output, not the host's entire context window. Keep unrelated transcripts and tools out of the active context. Private blocks must stay out of direct file reads as well as prompts.
10
13
 
11
- ### 1. Install fdeops (same as any other setup)
14
+ ## What compatibility means
12
15
 
13
- ```bash
14
- npx fdeops init my-client
15
- ```
16
+ - **CLI verified:** commands work without a model.
17
+ - **Transport verified:** the host can call a model or MCP server and receive a valid response.
18
+ - **Workflow verified:** that exact host/model combination selects tools, uses the correct client, preserves constraints, and returns a useful result.
16
19
 
17
- ### 2. Load the skill into your local model
20
+ These are separate checks. Model size alone does not establish quality, and FDEOps does not promise support for every model. Record the model/version, context setting, tool permissions, task, and actual outcome. Test a scope change, missing evidence and a refused approval before relying on a new model for client delivery.
18
21
 
19
- The file your model needs to read as system context:
20
-
21
- ```
22
- # If you cloned the repo:
23
- skills/fde/SKILL.md
24
-
25
- # If you ran `node bin/install.js` (also sets up hooks + adapters):
26
- ~/.claude/skills/fde/SKILL.md
27
- ```
28
-
29
- Either path works - same file. If you only want the local LLM workflow and skipped `install.js`, use the repo-local path directly.
30
-
31
- How you load it depends on your setup:
32
-
33
- | Tool | How to load |
34
- |------|-------------|
35
- | **Ollama + Open WebUI** | Paste the contents of `SKILL.md` into the system prompt field, or mount it as a file in your Modelfile |
36
- | **LM Studio** | Add `SKILL.md` path to the system prompt in chat settings |
37
- | **llama.cpp / server mode** | Pass `--system-prompt-file skills/fde/SKILL.md` |
38
- | **vLLM + chat UI** | Include as the system message in your chat template |
39
- | **Aider** | Run aider from your engagement workspace - it reads repo files including SKILL.md automatically |
40
- | **Continue.dev (VS Code)** | Add SKILL.md as a context provider in `.continue/config.json` |
41
- | **text-generation-webui** | Load SKILL.md content in the "Context" or "System prompt" tab |
42
- | **Jan.ai** | Paste into the system prompt field in assistant settings |
43
- | **GPT4All** | Add as system prompt in the model's chat configuration |
44
-
45
- ### 3. Set the engagement path
46
-
47
- Your local model needs to know where the engagement memory lives. Set the environment variable before starting your session:
48
-
49
- ```bash
50
- export FDEOPS_ENGAGEMENT=~/fde-engagements/my-client/.fde
51
- ```
52
-
53
- Or tell the model directly: "My engagement is at ~/fde-engagements/my-client/.fde"
54
-
55
- ### 4. Use it
56
-
57
- ```
58
- @fde I'm preparing for tomorrow's stakeholder meeting. The brief says payments API.
59
- ```
60
-
61
- The model reads SKILL.md, routes to the right skill, and produces artifacts in your `.fde/` folder.
62
-
63
- ## Model size recommendations
64
-
65
- The kit is detailed (30 skills, routing logic, evidence format, memory contract). Larger models handle it better:
66
-
67
- | Model class | Experience |
68
- |-------------|-----------|
69
- | **7-8B** (Llama 3.1 8B, Mistral 7B, Qwen 2.5 7B) | Handles individual skills (readout, log, land). May struggle with complex routing or multi-skill sessions. Good for the CLI-heavy workflow where you invoke skills explicitly. |
70
- | **13-34B** (Llama 3.1 13B, Mixtral 8x7B, Qwen 2.5 32B, DeepSeek-R1 32B) | Good across all domains. Routes correctly, follows memory contract, writes structured artifacts. Recommended minimum for full use. |
71
- | **70B+** (Llama 3.1 405B, DeepSeek V3, Qwen 2.5 72B) | Full capability. Handles regulated overlays, switch-clients, board-memo pyramid, runbook handoff. |
72
-
73
- ## The CLI works without ANY model
74
-
75
- Even if you can't run a local model (or you're at a regulated client with no AI permitted), the `fde` CLI gives you the deterministic tooling:
76
-
77
- ```bash
78
- fde scan # repo recon - hotspots, test gaps, AI components (git only)
79
- fde resume # load/create engagement memory
80
- fde log # structured append: decisions, risks, delivery, contacts
81
- fde receipts # "what did we agree?" - search memory with dates
82
- fde status # portfolio triage across all customers (red/amber/green)
83
- fde dashboard # offline HTML fieldbook across all engagements
84
- fde capture # session-end memory snapshot
85
- ```
86
-
87
- Zero network. Zero AI. Pure local Node.js reading git and markdown.
88
-
89
- ## Ollama Modelfile example
90
-
91
- ```dockerfile
92
- FROM llama3.1:70b
93
-
94
- # System prompt provided at runtime via --system flag
95
-
96
- PARAMETER temperature 0.3
97
- PARAMETER num_ctx 32768
98
- ```
99
-
100
- Then load the skill:
101
- ```bash
102
- ollama run my-fde-model --system "$(cat skills/fde/SKILL.md)"
103
- ```
104
-
105
- ## Tips for local models
106
-
107
- - **Context window matters.** SKILL.md + references can be large. Use a model with at least 8K context; 32K+ is ideal for loading skill references on demand.
108
- - **Temperature 0.2-0.4 works best.** The skills are structured - lower temperature keeps routing accurate and artifacts consistent.
109
- - **Use the CLI for mechanics.** Don't ask the model to do what the CLI already does deterministically. Use `fde scan` for repo recon, `fde log` for memory writes, `fde receipts` for searching. Let the model handle judgment, routing, and artifact drafting.
110
- - **Explicit skill invocation.** If a smaller model struggles with routing, you can invoke skills directly: "@fde run the discover phase" or "@fde use hold-scope." The model skips routing and goes straight to the skill.
22
+ See [verification results](../docs/verification.md) for the combinations actually exercised. No automatic Claude session hooks are implied for local agent hosts.
package/bin/check.js CHANGED
@@ -449,9 +449,9 @@ const hookCode = hook.replace(/^[ \t]*#.*$/gm, '')
449
449
  if (!hook.includes('FDEOPS_ENGAGEMENT')) {
450
450
  fail('session-start hook must read FDEOPS_ENGAGEMENT env var')
451
451
  } else ok('hook FDEOPS_ENGAGEMENT')
452
- if (!hookCode.includes('FDEOPS_ENGAGEMENT="$ENG_DIR" fde triage') ||
453
- !hookCode.includes('FDEOPS_ENGAGEMENT="$ENG_DIR" node "$FDE_CMD" triage')) {
454
- fail('session-start must run triage with its resolved engagement')
452
+ if (!hookCode.includes('FDEOPS_ENGAGEMENT="$ENG_DIR" fde resume') ||
453
+ !hookCode.includes('FDEOPS_ENGAGEMENT="$ENG_DIR" node "$FDE_CMD" resume')) {
454
+ fail('session-start must delegate bounded context and triage to resume with its resolved engagement')
455
455
  }
456
456
  // Token discipline: SessionStart must not dump the full skill (L1 progressive disclosure).
457
457
  // Strip comments before scanning for a real `cat …SKILL.md` / BOOTSTRAP inject.