fdeops 3.5.1 → 3.5.3

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
@@ -31,10 +31,10 @@ flowchart LR
 
 Works with **Claude Code** · **Cursor** · **Copilot** · **Devin** · **Gemini CLI** · any agent that reads SKILL.md
 
-<p align="center"><strong>The CLI (zero tokens, zero network)</strong></p>
+<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>
 
-<p align="center"><strong>The Fieldbook Dashboard (one offline HTML file)</strong></p>
+<p align="center"><strong>The Fieldbook Dashboard</strong></p>
 <p align="center"><img src="media/fieldbook-dashboard.png" alt="FDE Fieldbook - portfolio view" width="720"/></p>
 
 ---
@@ -46,9 +46,9 @@ Works with **Claude Code** · **Cursor** · **Copilot** · **Devin** · **Gemini
 | **Consultant or contractor at a client site** | Every session, you re-explain context. fdeops remembers for you. |
 | **Solutions architect bridging strategy and code** | You navigate politics AND architecture. fdeops has methods for both. |
 | **Agency engineer running 3-5 clients** | Client details blur together. One `.fde/` per customer, never cross-contaminated. |
-| **Forward Deployed Engineer** (Palantir, Anthropic, Databricks) | The role this was built for. 34 skills across the full engagement lifecycle. |
+| **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** | AI overlay: model selection, RAG, agents, governance, drift, cost at scale. |
+| **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,78 +67,80 @@ 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).
 
-One brain (`skills/fde/SKILL.md`), a thin pointer per tool:
+---
+
+## 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` |
 
-Each file just points at `@fde` - so the method, overlays, and memory stay in one place. Details: [`adapters/`](adapters/README.md).
-
----
-
-## Who does what
-
-| Role | Who | What they do |
-|------|-----|----------------|
-| **You** | **Human** on the engagement | Stakeholder meetings, calls, judgment, sign-off, typing `@fde`, owning what ships |
-| **AI coding agent** | **Software** on your laptop (e.g. Claude Code) - **not** a human colleague | Loads the `@fde` skill, runs the phase methods, writes code and `.fde/` artifacts |
-| **`@fde`** | **One skill** inside the AI agent | Hears your situation, routes to the right phase, does that phase's work |
-
-**In this repo, "agent" always means the AI coding agent, never a person.**
+Each adapter points at the same `@fde` skill, so the methodology and memory stay consistent across tools. Details: [`adapters/`](adapters/README.md).
 
 ---
 
@@ -146,127 +148,32 @@ Each file just points at `@fde` - so the method, overlays, and memory stay in on
 
 ```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)
 ```
 
-| Layer | What | Where |
-|-------|------|-------|
-| **Surface** | One command: `@fde` | You type it |
-| **Router** | Hears your situation, picks the skill | `SKILL.md` |
-| **Skills** | 34 methods across 6 domains | `references/` |
-| **Overlays** | Activate on signal (AI, fintech, healthcare, gov, artifacts) | Layer on top |
-| **Memory** | `.fde/` - engagement record, per customer | Your machine |
-
----
-
-## The basic workflow
-
-You only ever type **`@fde`**. The AI coding agent reads `context.md` from your engagement folder, routes to the matching skill, and follows that skill's method:
-
 1. **Describe** - tell the agent what's happening ("new client", "production is down", "need a board update")
 2. **Route** - the system picks the right skill from 34 options across 6 domains
 3. **Execute** - the skill's method runs, artifacts are written to `.fde/`, you review at checkpoints
 
 ---
 
-## The 6 domains
-
-### 1. Embed & Trust
-*First days. Getting access, building credibility, understanding scope.*
-
-| Skill | What it does |
-|-------|-------------|
-| **land** | First 48 hours: interrogate the brief, map stakeholders, define success before code |
-| **audit** | Taking over mid-project: verify claims, find the load-bearing wall |
-| **stakeholder-radar** | Map who decides, who blocks, who's about to escalate |
-| **trust-engineering** | The trust ladder from observer to trusted; navigate AI policy |
-| **scope-defense** | "Let me place it": scope receipts, the accumulation conversation |
-
-### 2. Discover & Diagnose
-*Finding the real problem. Testing what the brief claims.*
-
-| Skill | What it does |
-|-------|-------------|
-| **discover** | Scan repo + hunt the workaround + **workshop facilitation** + **data estate assessment** |
-| **assumption-audit** | Extract untested assumptions, classify by blast radius, kill the riskiest first |
-| **use-case-scoring** | Score on value x urgency x alignment x data readiness / complexity |
-| **sketch** | Prototype the killer assumption in one day; kill fast, log the learning |
-
-### 3. Plan & Align
-*Sequencing work and getting sponsor alignment.*
-
-| Skill | What it does |
-|-------|-------------|
-| **plan** | Work backwards from success + **estimation** (3-point sizing) + **migration strategy** |
-| **business-case** | Cost of doing nothing -> investment -> return -> sensitivity check |
-| **options-analysis** | Three genuine options (conservative / pragmatic / ambitious) |
-| **initiative-triage** | 20 things are "urgent"; pick 3 for Now, make trade-offs visible |
-
-### 4. Build & Guard
-*Safe implementation on someone else's codebase.*
-
-| Skill | What it does |
-|-------|-------------|
-| **build** | Blast radius + legacy safety + **integration design** + **team amplification** |
-| **incremental-build** | Vertical slices, 100-300 lines each, visible progress every 2-3 days |
-| **test-on-legacy** | Characterise first, Strangler Fig, spot lying tests |
-| **blast-radius** | Trace dependencies, classify impact (CONTAINED -> IRREVERSIBLE) |
-| **debug** | Systematic: reproduce -> isolate -> one hypothesis -> verify |
-| **rescue** | Production fire, trust fire, wrong-brief-mid-build, **or full pivot** |
-| **security-audit** | Threat model in 5 minutes, STRIDE pass, secrets scan |
-| **observability** | Define "working" before instrumenting; the four metrics |
-
-### 5. Ship & Verify
-*Getting to production without surprises.*
-
-| Skill | What it does |
-|-------|-------------|
-| **ship** | Pre-flight + canary + rollback + **scale-readiness gate** + **progressive adoption** |
-| **review** | Scope first (did we build what was agreed), then safety |
-| **rollback-drill** | Test the escape route on staging before you need it at 2am |
-| **qa-live** | Test from the user's chair, real browser, five perspectives |
-
-### 6. Operate & Close
-*Running the engagement and ending it well.*
-
-| Skill | What it does |
-|-------|-------------|
-| **status** | Sponsor update from the week's actual record |
-| **demo-prep** | The one number, live-vs-canned, five hard questions |
-| **debrief** | Walk out of any meeting -> decisions, signals, actions in memory |
-| **exec-narrative** | Pyramid: governing thought, three supports, SCQA frame |
-| **dashboard** | Portfolio view across all customers, trust-ordered |
-| **multi-customer-ops** | Daily triage, context-switch, cross-contamination prevention |
-| **close** | Retrospective, the 2am handoff document, what we learned |
-| **handoff-engineering** | Operations runbook, knowledge transfer, confidence scoring |
-| **pattern-extract** | If you did it twice, encode it; patterns are compound interest |
-
-### Overlays (activate on signal)
-
-| Overlay | Triggers on | What it adds |
-|---------|------------|-------------|
-| **ai** | AI, ML, LLM, model, embeddings, RAG, agents | Model selection, RAG architecture, agent safety, governance, drift monitoring, cost management |
-| **artifacts** | deck, slides, report, governance, compliance | Executive decks, governance frameworks, ADRs, compliance packs, value reports |
-| **fintech** | payments, PCI, banking, cardholder data | Idempotency, transaction integrity, fraud signals, silent-failure prevention |
-| **healthcare** | PHI, HIPAA, patient data | De-identification, minimum-necessary, audit trails |
-| **gov** | FedRAMP, ATO, CUI, classified | Authority boundaries, CUI marking, continuous monitoring |
+## 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 | 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 |
 
-## What makes fdeops different
+**Overlays** activate automatically when your engagement involves AI projects, executive reporting, fintech, healthcare, or government compliance.
 
-| Other skill repos | fdeops |
-|---|---|
-| No client memory - re-paste every session | `.fde/` writes itself; next session loads automatically |
-| No engagement politics - pure engineering | Skills for stakeholder radar, trust, scope defense, exec narratives |
-| No multi-customer support | One folder per client, portfolio dashboard, hard isolation |
-| Flat list of skills - find it yourself | Type `@fde`, describe the situation, it routes |
-| Generic engineering or startup advice | Built for embed work: brownfield safety, earned access, sponsor alignment, workshop facilitation |
-| No document generation | **Artifacts overlay:** governance frameworks, exec decks, compliance packs, ADRs from memory |
-| No AI project guidance | **AI overlay:** model selection, RAG, agents, governance, drift, cost at scale |
+Full skill details: [docs/skills-reference.md](docs/skills-reference.md)
 
 ---
 
@@ -287,37 +194,22 @@ Your **fieldbook** - one per client, private to you, plain markdown:
 | `risks.md` | Live risk register | all phases |
 | `delivery.md` | What shipped, business value, rollback, pulse, adoption metrics | build / ship |
 
-Every claim carries evidence: `(ops lead, Day 5)` · `(churn: 47/90d)` · `(stated, unverified)`.
+Every claim is tagged with its source and date so you can defend it in front of skeptical stakeholders.
 
 ---
 
-## The CLI (works without AI)
+## The CLI
+
+These commands run locally on your machine. No AI needed, no API costs, works offline.
 
 ```bash
-fde scan       # day-1 recon: hotspots x tests, "temporary" code, AI calls, secrets
+fde scan       # day-1 recon: hotspots, test gaps, "temporary" code, AI components, secrets
 fde resume     # initialize or resume an engagement
 fde log        # write decisions, risks, delivery, contacts
 fde receipts   # search memory with dates
 fde capture    # session-end snapshot
 fde status     # portfolio triage across all customers
-fde dashboard  # render every engagement into one offline fieldbook.html (0 tokens)
-```
-
----
-
-## What's inside
-
-```
-bin/fde.js              the CLI - deterministic core, works without AI:
-                          fde scan · resume · log · receipts · capture · status · dashboard
-skills/fde/
-  SKILL.md              the router: voice, memory contract, 6-domain routing
-  references/
-    34 skill files      one method per file
-    5 overlays          ai.md, artifacts.md, fintech.md, healthcare.md, gov.md
-hooks/                  session-start, session-stop, pre-compact
-templates/.fde/         the 10 core memory files an init creates
-docs/                   install guides, schema, methodology
+fde dashboard  # render every engagement into one offline dashboard
 ```
 
 ---
@@ -331,8 +223,6 @@ docs/                   install guides, schema, methodology
 - **Map before moving** - unknown terrain gets characterisation tests
 - **Thin slices** - ship learning, not theatre
 - **One customer, one folder** - context never bleeds
-- **AI degrades silently** - monitor outputs, not just uptime
-- **Scale readiness is organizational** - not just technical
 
 ---
 
@@ -348,4 +238,4 @@ cd fdeops && git pull && node bin/install.js
 
 Maintained by **[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. Feedback via [Issues](https://github.com/suboss87/fdeops/issues) - see [CONTRIBUTING.md](CONTRIBUTING.md).
 
-[FDE Methodology](FDE-METHODOLOGY.md) · [ATTRIBUTION.md](ATTRIBUTION.md) · [SECURITY.md](SECURITY.md) · [PRIVACY.md](PRIVACY.md) · [Repo layout](docs/REPO_LAYOUT.md) · MIT
+[FDE Methodology](FDE-METHODOLOGY.md) · [ATTRIBUTION.md](ATTRIBUTION.md) · [SECURITY.md](SECURITY.md) · [PRIVACY.md](PRIVACY.md) · [Repo layout](docs/REPO_LAYOUT.md) · [Skills reference](docs/skills-reference.md) · MIT

package/bin/check.js

@@ -108,11 +108,8 @@ else ok('README no demo gif')
 for (const section of [
   'How it works',
   'Quickstart',
-  'The basic workflow',
-  "What's inside",
   'Engagement memory',
   'Who this is for',
-  'Who does what',
   'Without fdeops vs with fdeops',
   'Principles',
 ]) {
@@ -121,9 +118,6 @@ for (const section of [
 if (!readme.includes('AI coding agent')) {
   fail('README must say AI coding agent (not ambiguous "agent")')
 }
-if (!/agent.*always means the AI|“agent” always means/i.test(readme)) {
-  fail('README must define that agent means AI, not human')
-}
 ok('README clarity sections')
 
 if (readme.includes('your-client-repo')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops",
-  "version": "3.5.1",
+  "version": "3.5.3",
   "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",