fdeops 3.24.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 (21) hide show
  1. package/README.md +78 -216
  2. package/adapters/LOCAL-LLM.md +14 -102
  3. package/bin/check.js +3 -3
  4. package/bin/fde.js +517 -375
  5. package/bin/install.js +74 -51
  6. package/bin/lib/context.js +85 -0
  7. package/bin/lib/delivery-gaps.js +34 -0
  8. package/bin/lib/fieldbook-client.js +41 -10
  9. package/bin/lib/font-css.js +115 -0
  10. package/bin/lib/install-paths.js +53 -0
  11. package/bin/lib/provenance.js +42 -0
  12. package/bin/lib/render.js +57 -74
  13. package/bin/lib/value-ledger.js +40 -0
  14. package/hooks/session-start +18 -84
  15. package/mcp/fdeops-ingest/package.json +1 -1
  16. package/package.json +2 -2
  17. package/plugin.json +1 -1
  18. package/skills/fde/SKILL.md +6 -5
  19. package/skills/fde/references/plan.md +2 -0
  20. package/skills/fde/references/poc.md +11 -3
  21. package/skills/fde/references/ship.md +3 -1
package/README.md CHANGED
@@ -1,123 +1,51 @@
1
1
  # FDEOps
2
2
 
3
- **Turn a customer request into the smallest useful delivery - and keep the evidence that it worked.**
3
+ **The local engagement OS for AI coding agents.**
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 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 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.
8
-
9
- Keep your existing coding skills. FDEOps supplies the customer context, scope, approvals, and acceptance criteria around their engineering work.
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`.
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 |
28
13
 
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.
14
+ You make the judgments and obtain customer approval. The record helps you explain them later.
30
15
 
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.
16
+ <img width="1536" height="1024" alt="fdeops" src="https://github.com/user-attachments/assets/2bcb8739-55ee-445d-8a1a-8b38433b7b58" />
41
17
 
42
18
  ## Quick Start
43
19
 
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
47
-
48
- ```bash
49
- npx fdeops demo
50
- ```
51
-
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.
57
-
58
- ### 2. Install the agent 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.
59
21
 
60
22
  ```bash
61
23
  npx skills add suboss87/fdeops --skill fde
62
24
  ```
63
25
 
64
- In your coding agent, with the customer workspace open:
26
+ Open the client workspace and tell your agent:
65
27
 
66
28
  ```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.
29
+ @fde this is client01
70
30
  ```
71
31
 
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.
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.
73
33
 
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:
85
-
86
- ```bash
87
- npx fdeops dashboard --open
88
- ```
89
-
90
- Continue with the [five-minute walkthrough and daily guide](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`.
91
35
 
92
36
  <details>
93
- <summary><b>Claude Code plugin</b></summary>
37
+ <summary>Host installation and offline use</summary>
38
+
39
+ Claude Code plugin:
94
40
 
95
41
  ```text
96
42
  /plugin marketplace add suboss87/fdeops
97
43
  /plugin install fdeops@fdeops
98
44
  ```
99
45
 
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).
101
-
102
- </details>
103
-
104
- <details>
105
- <summary><b>Cursor, Codex, Gemini CLI, and Copilot</b></summary>
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.
106
47
 
107
- After installing the skill, run this in the customer workspace to add host pointers:
108
-
109
- ```bash
110
- npx fdeops adapters .
111
- ```
112
-
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).
114
-
115
- </details>
116
-
117
- <details>
118
- <summary><b>Install from a checkout / offline preparation</b></summary>
119
-
120
- On a connected machine:
48
+ Clone installation:
121
49
 
122
50
  ```bash
123
51
  git clone https://github.com/suboss87/fdeops.git
@@ -125,172 +53,106 @@ cd fdeops
125
53
  node bin/install.js
126
54
  ```
127
55
 
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).
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).
129
57
 
130
58
  </details>
131
59
 
132
- ## Your daily workflow
133
-
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 |
140
-
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.
142
-
143
- ## All 30 Skills
144
-
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.
146
-
147
- Full detail: [docs/skills-reference.md](docs/skills-reference.md).
148
-
149
- ### Land
150
-
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 |
60
+ ## Commands
158
61
 
159
- ### Discover
62
+ One command per stage. Skills load automatically. Describe the situation to `@fde`; the Claude Code plugin also provides these slash commands.
160
63
 
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 |
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 |
167
72
 
168
- ### Plan
73
+ Daily requests: `/debrief`, `/prep`, `/receipts`, `/readout`, and `/trust`. Revisit earlier stages when evidence changes; a new incident does not require restarting discovery.
169
74
 
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 |
75
+ ## One loop you can defend
176
76
 
177
- ### Ship
77
+ Paste messy notes after a meeting:
178
78
 
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" |
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
+ ```
186
84
 
187
- ### Outcome
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.
188
88
 
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 |
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.
198
90
 
199
- ### Close
91
+ ## Your daily fieldbook
200
92
 
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" |
93
+ ![FDEOps dark dashboard showing next actions and attention gaps across three fictional clients](media/fieldbook-preview.png)
208
94
 
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).
95
+ *Fictional client records in the built-in dark theme. The report works offline.*
210
96
 
211
- Optional pull: you add the source MCP; we **pull** on request. [mcp/recipes/](mcp/recipes/)
97
+ ```bash
98
+ npx fdeops dashboard --open # this client
99
+ npx fdeops dashboard --all --open # all clients
100
+ ```
212
101
 
213
- ---
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.
214
103
 
215
104
  ## How Skills Work
216
105
 
106
+ One entry, one source of methodology, one record per client:
107
+
217
108
  ```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
109
+ @fde + your situation → one relevant skill → reviewed work → .fde/ → fieldbook
227
110
  ```
228
111
 
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.
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.
230
113
 
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).
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/).
232
115
 
233
116
  ## Engagement memory (`.fde/`)
234
117
 
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.
236
-
237
- | File | What it answers |
118
+ | Record | What it preserves |
238
119
  |---|---|
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? |
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 |
245
124
 
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.
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.
247
126
 
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).
127
+ ## Who this is for
249
128
 
250
- [Memory schema](docs/schema.md) · [Multi-client usage](docs/USAGE.md#multiple-engagements)
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.
251
130
 
252
131
  ## Principles
253
132
 
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.
260
-
261
- ## Who this is for
262
-
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.
264
-
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.
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.
266
139
 
267
140
  ## Your data stays yours
268
141
 
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.
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.
274
143
 
275
- [PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
144
+ [Privacy](PRIVACY.md) · [Security](SECURITY.md)
276
145
 
277
- ## Quality and contributing
146
+ ## Project Structure
278
147
 
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.
280
-
281
- From a checkout:
282
-
283
- ```bash
284
- npm run check
285
- npm run test:skill-routing
286
- ```
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.
287
149
 
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.
150
+ ## Contributing
289
151
 
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.
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).
291
153
 
292
- [CONTRIBUTING.md](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md)
154
+ [Contribution guide](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md)
293
155
 
294
156
  ## License
295
157
 
296
- [MIT](LICENSE) - use these skills on client work.
158
+ MIT - use FDEOps on client work. Preserve applicable license notices when redistributing.
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.