fdeops 3.5.2 → 3.5.4

package/README.md

@@ -20,7 +20,7 @@ flowchart LR
     B --> F["Build & Guard"]
     B --> G["Ship & Verify"]
     B --> H["Operate & Close"]
-    C --> I[".fde/ memory\n(auto-written)"]
+    C --> I[".fde/ memory\n(written as you work)"]
     D --> I
     E --> I
     F --> I
@@ -29,7 +29,7 @@ flowchart LR
     I --> J["Next session\nloads automatically"]
 ```
 
-Works with **Claude Code** · **Cursor** · **Copilot** · **Devin** · **Gemini CLI** · any agent that reads SKILL.md
+Works with **Claude Code** · **Cursor** · **Copilot** · **Devin** · **Gemini CLI** · **Ollama** · **LM Studio** · any model that reads SKILL.md
 
 <p align="center"><strong>The CLI</strong></p>
 <p align="center"><img src="media/terminal-demo.svg" alt="fde CLI - status, scan, dashboard" width="720"/></p>
@@ -48,7 +48,7 @@ Works with **Claude Code** · **Cursor** · **Copilot** · **Devin** · **Gemini
 | **Agency engineer running 3-5 clients** | Client details blur together. One `.fde/` per customer, never cross-contaminated. |
 | **Forward Deployed Engineer** | The role this was built for. 34 skills across the full engagement lifecycle. |
 | **Technical founder doing client work solo** | You ARE the team. The agent becomes your second brain. |
-| **Enterprise programme lead** | Running AI transformations? Built-in methods for model selection, agent safety, governance, and cost management. |
+| **Enterprise programme lead** | Leading AI transformations? Built-in methods for model selection, agent safety, governance, and cost management. |
 
 ---
 
@@ -56,10 +56,10 @@ Works with **Claude Code** · **Cursor** · **Copilot** · **Devin** · **Gemini
 
 | | **Without fdeops** | **With fdeops** |
 |---|-------------------|----------------|
-| **Memory** | Re-paste context every session | `.fde/` writes itself - next session starts where today ended |
-| **Discovery** | Agent treats the brief as the task | Agent scans churn, test gaps, "temporary" code; hands you the real problem with evidence |
-| **Multiple customers** | Details blur between clients | One folder per customer, auto-loaded, never merged |
-| **The output** | Advice you already knew | An artifact you carry into the sponsor meeting |
+| **Monday morning** | Re-paste last week's context, explain the stakeholders again | Agent opens with "last session you were on the ingest retry - CTO demo is Friday" |
+| **Scope creep** | Five "small" additions absorbed silently, timeline slips | Receipts timestamped - you walk into the sponsor meeting with evidence |
+| **Multiple customers** | Wrong client name in a status update, details blur | One folder per customer, context-switch protocol, cross-contamination checklist |
+| **The sponsor meeting** | "We completed the API endpoint" | "Manual reconciliation dropped from 3 FTEs to 0.5 - here's the rollback if it turns" |
 
 ---
 
@@ -67,75 +67,92 @@ Works with **Claude Code** · **Cursor** · **Copilot** · **Devin** · **Gemini
 
 **Requires:** [Node.js](https://nodejs.org) >= 18
 
-```bash
-# Option A: Skills CLI (any agent)
-npx skills add suboss87/fdeops
-
-# Option B: Clone + install
-git clone https://github.com/suboss87/fdeops.git
-cd fdeops && node bin/install.js
-```
+### 1. Install and create your first engagement
 
-Start your first engagement:
 ```bash
-node bin/install.js init my-client
-# or: npx fdeops init my-client (engagement memory at ~/fde-engagements/my-client/.fde/)
+npx fdeops init my-client   # creates engagement memory at ~/fde-engagements/my-client/.fde/
 ```
 
-Point the AI coding agent at it:
+### 2. Point your AI agent at it
+
 ```bash
 export FDEOPS_ENGAGEMENT=~/fde-engagements/my-client/.fde
 ```
 
-Then talk to your agent:
+### 3. Start working
+
 ```
 @fde I'm on site. First stakeholder meeting tomorrow. Brief says fix the payments API.
 ```
 
-The system routes to `land` and starts working:
+The agent routes to `land` and starts thinking with you:
+
+```
+Brief says payments API - but nobody named who owns the budget for this
+work. That's your first question tomorrow. And the brief has no
+out-of-scope section, which means scope creep is pre-authorised.
+
+Watch for the internal dev who got passed over for this contract - if
+there is one, you want them on your side before the first standup.
+Also: what does failure look like to the sponsor personally, not the
+project charter? That answer shapes everything.
+
+I'll draft brief.md, success.md, stakeholders.md, trust-profile.md
+after you come back with notes.
+```
+
+Day 15, the memory has compounded:
+
+```
+@fde What's the priority today?
 ```
-Routing to: land (first engagement, day 1)
 
-Before tomorrow's meeting, I need to understand a few things:
+```
+Last session you were finishing the ingest retry on staging. CTO demo
+is Friday and status hasn't gone out since Tuesday. The finance
+controller still hasn't seen a working demo - that's a risk.
 
-  1. Who owns the budget for this work? (the brief doesn't say)
-  2. What's NOT in scope? (undefined scope = unlimited scope)
-  3. Is there an internal dev who was passed over for this work?
-  4. What's their AI policy? (do they know I'm an AI agent?)
+Globex has been quiet for 3 days - trust signal amber.
 
-Writing: brief.md, success.md, stakeholders.md, trust-profile.md
-Next: bring answers from the meeting, then we discover the real problem.
+I'd send the CTO status first, then finish the retry, then check in
+on Globex before end of day. What do you want to tackle?
 ```
 
-That's it. The system takes over from there.
+That's the difference. Day 1: it coaches your preparation. Day 15: it picks up where yesterday ended and triages across customers.
 
-### Use it in any tool
+> **Other install methods:** `npx skills add suboss87/fdeops` (Skills CLI) or `git clone https://github.com/suboss87/fdeops.git && cd fdeops && node bin/install.js` (manual).
+
+---
+
+## Works with any AI coding tool
 
 One skill file powers every tool. Install adapters for your setup:
 
 ```bash
-node bin/install.js adapters ~/fde-engagements/my-client
-# or: npx fdeops@latest adapters ~/fde-engagements/my-client
+npx fdeops adapters ~/fde-engagements/my-client
 ```
 
-| Tool | Pointer file it reads |
-|------|-----------------------|
-| Claude Code | plugin + `~/.claude/FDEOPS-CLAUDE.md` |
+| Tool | What it reads |
+|------|--------------|
+| Claude Code | Plugin + `~/.claude/FDEOPS-CLAUDE.md` |
 | Codex / OpenAI / generic | `AGENTS.md` |
 | Gemini CLI | `GEMINI.md` |
 | Cursor | `.cursor/rules/fde.mdc` |
 | GitHub Copilot | `.github/copilot-instructions.md` |
+| **Local LLMs** (Ollama, LM Studio, llama.cpp, vLLM) | Load `SKILL.md` as system prompt |
 
 Each adapter points at the same `@fde` skill, so the methodology and memory stay consistent across tools. Details: [`adapters/`](adapters/README.md).
 
+> **No cloud dependency.** fdeops calls no external API. The AI skill is a markdown file your model reads. The CLI is local Node.js. Works fully offline, fully air-gapped, fully private. See [`adapters/LOCAL-LLM.md`](adapters/LOCAL-LLM.md) for local model setup.
+
 ---
 
 ## How it works
 
 ```text
   YOU (human)                         AI CODING AGENT (software)
-  meetings, judgment         @fde      routes -> right skill -> does the work
-        |                 ----->      .fde/ memory (self-writing)
+  meetings, judgment         @fde      routes -> right skill -> drafts the artifact
+        |                 ----->      .fde/ memory (written as you work)
         |                                   |
         +--------------->  client workspace (code, VPN, tickets)
 ```
@@ -146,14 +163,14 @@ Each adapter points at the same `@fde` skill, so the methodology and memory stay
 
 ---
 
-## The 6 domains — 34 skills + 5 overlays
+## The 6 domains - 34 skills + 5 overlays
 
 | Domain | Skills | What it covers |
 |--------|--------|---------------|
 | **Embed & Trust** | land, audit, stakeholder-radar, trust-engineering, scope-defense | First days: access, credibility, scope |
 | **Discover & Diagnose** | discover, assumption-audit, use-case-scoring, sketch | Finding the real problem behind the brief |
 | **Plan & Align** | plan, business-case, options-analysis, initiative-triage | Sequencing work, getting sponsor alignment |
-| **Build & Guard** | build, incremental-build, test-on-legacy, blast-radius, debug, rescue, security-audit, observability | Safe implementation on their codebase |
+| **Build & Guard** | build, incremental-build, test-on-legacy, blast-radius, debug, rescue, security-audit, observability | Helping you build safely on their codebase |
 | **Ship & Verify** | ship, review, rollback-drill, qa-live | Getting to production without surprises |
 | **Operate & Close** | status, demo-prep, debrief, exec-narrative, dashboard, multi-customer-ops, close, handoff-engineering, pattern-extract | Running and ending the engagement well |
 

package/adapters/LOCAL-LLM.md

@@ -0,0 +1,106 @@
+# fdeops - Local LLM Setup
+
+Use fdeops with **any local model** - Ollama, LM Studio, llama.cpp, vLLM, Open WebUI, or any inference server that accepts a system prompt.
+
+## Why it works
+
+fdeops is a SKILL.md file + markdown memory + a Node.js CLI. It calls no external API. The AI does the methodology; the CLI does the mechanics. Any model that can read a markdown system prompt can run fdeops.
+
+## Setup
+
+### 1. Install fdeops (same as any other setup)
+
+```bash
+npx fdeops init my-client
+```
+
+### 2. Load the skill into your local model
+
+The file your model needs to read as system context:
+
+```
+~/.claude/skills/fde/SKILL.md
+```
+
+How you load it depends on your setup:
+
+| Tool | How to load |
+|------|-------------|
+| **Ollama + Open WebUI** | Paste the contents of `SKILL.md` into the system prompt field, or mount it as a file in your Modelfile |
+| **LM Studio** | Add `SKILL.md` path to the system prompt in chat settings |
+| **llama.cpp / server mode** | Pass `--system-prompt-file ~/.claude/skills/fde/SKILL.md` |
+| **vLLM + chat UI** | Include as the system message in your chat template |
+| **Aider** | Run aider from your engagement workspace - it reads repo files including SKILL.md automatically |
+| **Continue.dev (VS Code)** | Add SKILL.md as a context provider in `.continue/config.json` |
+| **text-generation-webui** | Load SKILL.md content in the "Context" or "System prompt" tab |
+| **Jan.ai** | Paste into the system prompt field in assistant settings |
+| **GPT4All** | Add as system prompt in the model's chat configuration |
+
+### 3. Set the engagement path
+
+Your local model needs to know where the engagement memory lives. Set the environment variable before starting your session:
+
+```bash
+export FDEOPS_ENGAGEMENT=~/fde-engagements/my-client/.fde
+```
+
+Or tell the model directly: "My engagement is at ~/fde-engagements/my-client/.fde"
+
+### 4. Use it
+
+```
+@fde I'm preparing for tomorrow's stakeholder meeting. The brief says payments API.
+```
+
+The model reads SKILL.md, routes to the right skill, and produces artifacts in your `.fde/` folder.
+
+## Model size recommendations
+
+The methodology is detailed (34 skills, routing logic, evidence format, memory contract). Larger models handle it better:
+
+| Model class | Experience |
+|-------------|-----------|
+| **7-8B** (Llama 3.1 8B, Mistral 7B, Qwen 2.5 7B) | Handles individual skills (status, log, land). May struggle with complex routing or multi-skill sessions. Good for the CLI-heavy workflow where you invoke skills explicitly. |
+| **13-34B** (Llama 3.1 70B-Q4, 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 methodology use. |
+| **70B+** (Llama 3.1 405B, DeepSeek V3, Qwen 2.5 72B) | Full capability. Handles regulated overlays, multi-customer ops, exec-narrative pyramid structure, complex handoff engineering. |
+
+## The CLI works without ANY model
+
+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:
+
+```bash
+fde scan          # repo recon - hotspots, test gaps, AI components (git only)
+fde resume        # load/create engagement memory
+fde log           # structured append: decisions, risks, delivery, contacts
+fde receipts      # "what did we agree?" - search memory with dates
+fde status        # portfolio triage across all customers (red/amber/green)
+fde dashboard     # offline HTML fieldbook across all engagements
+fde capture       # session-end memory snapshot
+```
+
+Zero network. Zero AI. Pure local Node.js reading git and markdown.
+
+## Ollama Modelfile example
+
+```dockerfile
+FROM llama3.1:70b
+
+SYSTEM """
+{{- .SystemPrompt -}}
+"""
+
+PARAMETER temperature 0.3
+PARAMETER num_ctx 32768
+```
+
+Then load the skill:
+```bash
+ollama run my-fde-model --system "$(cat ~/.claude/skills/fde/SKILL.md)"
+```
+
+## Tips for local models
+
+- **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.
+- **Temperature 0.2-0.4 works best.** The methodology is structured - lower temperature keeps routing accurate and artifacts consistent.
+- **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.
+- **Explicit skill invocation.** If a smaller model struggles with routing, you can invoke skills directly: "@fde run the discover phase" or "@fde use scope-defense." The model skips routing and goes straight to the method.

package/adapters/README.md

@@ -11,8 +11,9 @@
 | Gemini CLI | `GEMINI.md` | `GEMINI.md` |
 | Cursor | `.cursor/rules/fde.mdc` | `cursor.fde.mdc` |
 | GitHub Copilot | `.github/copilot-instructions.md` | `copilot-instructions.md` |
+| Local LLMs (Ollama, LM Studio, llama.cpp, vLLM) | Load `SKILL.md` as system prompt | [`LOCAL-LLM.md`](LOCAL-LLM.md) (guide) |
 
-`AGENTS.md` is the emerging cross-tool standard - many agents read it, so it doubles as the universal fallback.
+`AGENTS.md` is the emerging cross-tool standard - many agents read it, so it doubles as the universal fallback. For local/self-hosted models, see [`LOCAL-LLM.md`](LOCAL-LLM.md).
 
 ## Install them in one command
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops",
-  "version": "3.5.2",
+  "version": "3.5.4",
   "description": "Field kit for engineers embedded in client work - a real CLI (recon, memory, portfolio), one @fde skill with field judgment on top, and hooks that make it automatic. Claude Code plugin and any agent that loads skills.",
   "bin": {
     "fdeops": "bin/install.js",
@@ -38,7 +38,10 @@
     "codex",
     "gemini-cli",
     "copilot",
-    "agents-md"
+    "agents-md",
+    "ollama",
+    "local-llm",
+    "lm-studio"
   ],
   "repository": {
     "type": "git",