npm - fdeops - Versions diffs - 3.5.0 → 3.5.2 - Mend

fdeops 3.5.0 → 3.5.2

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 (3) hide show

package/README.md CHANGED Viewed

@@ -1,8 +1,15 @@
-# fdeops - The Operating System for Forward Deployed Engineers
+# fdeops
-> **One command. Six domains. Your second brain for client engagements.**
+[![npm version](https://img.shields.io/npm/v/fdeops)](https://www.npmjs.com/package/fdeops)
+[![CI](https://github.com/suboss87/fdeops/actions/workflows/validate.yml/badge.svg)](https://github.com/suboss87/fdeops/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
-You type **`@fde`**, describe your situation, and the system routes to the right method - from first stakeholder meeting to final handoff. Every skill writes its output to your private engagement memory (`.fde/`), so tomorrow starts where today ended. No re-pasting context. No maintaining notes. No picking from a catalog.
+You embed at a client site. You bridge strategy and code. You ship on their systems, not yours.
+Every morning you open your AI coding agent, and it has no idea what happened yesterday. You re-paste the same context. You explain the stakeholders again. You remind it about the scope change from Tuesday. Meanwhile, the real problem - the one the brief didn't mention - sits undiscovered because nobody asked the right questions on day one.
+**fdeops fixes this.** It gives your AI agent a complete engagement methodology and a private memory that writes itself. You type `@fde`, describe your situation, and the right method runs - from first stakeholder meeting to final handoff. Tomorrow's session starts exactly where today ended.
 ```mermaid
 flowchart LR
@@ -24,23 +31,24 @@ 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>
 ---
-## Who does what
-| Role | Who | What they do |
-|------|-----|----------------|
-| **You (the FDE)** | **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 |
+## Who this is for
-**In this repo, "agent" always means the AI coding agent, never a person.**
+| You are... | fdeops helps when... |
+|----------|-------------------|
+| **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** | 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. |
 ---
@@ -57,6 +65,8 @@ Works with **Claude Code** · **Cursor** · **Copilot** · **Devin** · **Gemini
 ## Quickstart
+**Requires:** [Node.js](https://nodejs.org) >= 18
 ```bash
 # Option A: Skills CLI (any agent)
 npx skills add suboss87/fdeops
@@ -82,11 +92,26 @@ Then talk to your agent:
 @fde I'm on site. First stakeholder meeting tomorrow. Brief says fix the payments API.
 ```
+The system routes to `land` and starts working:
+```
+Routing to: land (first engagement, day 1)
+Before tomorrow's meeting, I need to understand a few things:
+  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?)
+Writing: brief.md, success.md, stakeholders.md, trust-profile.md
+Next: bring answers from the meeting, then we discover the real problem.
+```
 That's it. The system takes over from there.
 ### Use it in any tool
-One brain (`skills/fde/SKILL.md`), a thin pointer per tool. Wire up an engagement workspace for every AI tool you use:
+One skill file powers every tool. Install adapters for your setup:
 ```bash
 node bin/install.js adapters ~/fde-engagements/my-client
@@ -101,135 +126,40 @@ node bin/install.js adapters ~/fde-engagements/my-client
 | 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).
+Each adapter points at the same `@fde` skill, so the methodology and memory stay consistent across tools. Details: [`adapters/`](adapters/README.md).
 ---
 ## How it works
 ```text
-  YOU (human FDE)                    AI CODING AGENT (software)
-  meetings, judgment        @fde      routes → right skill → does the work
-        │                 ─────►      .fde/ memory (self-writing)
-        │                                   │
-        └──────────────►  client workspace (code, VPN, tickets)
+  YOU (human)                         AI CODING AGENT (software)
+  meetings, judgment         @fde      routes -> right skill -> does the work
+        |                 ----->      .fde/ memory (self-writing)
+        |                                   |
+        +--------------->  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 × urgency × alignment × 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 | Safe implementation 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 | FDE-specific: 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)
 ---
@@ -250,51 +180,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 × 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)
-```
----
-## Who this is for
-| You are... | fdeops helps when... |
-|----------|-------------------|
-| **New to embed work** | You get a method per phase, not just encouragement |
-| **Senior operator, solo on site** | The agent is your second brain: memory + grunt work |
-| **Multi-client consultant** | One `.fde/` per customer, never cross-contaminated |
-| **Running AI transformations** | AI overlay: model selection → RAG → agents → scale → governance |
-| **Enterprise programme lead** | Estimation, migration strategy, scale-readiness, governance artifacts |
-**Works with:** Claude Code, Cursor, Copilot, Windsurf, Cline, Devin, Gemini CLI - any agent that reads SKILL.md.
----
-## 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
 ```
 ---
@@ -308,8 +209,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
 ---
@@ -323,6 +222,6 @@ cd fdeops && git pull && node bin/install.js
 ## Contributing
-Maintained by **Subash Natarajan**. Feedback via [Issues](https://github.com/suboss87/fdeops/issues) - see [CONTRIBUTING.md](CONTRIBUTING.md).
+Maintained by **[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. Feedback via [Issues](https://github.com/suboss87/fdeops/issues) - see [CONTRIBUTING.md](CONTRIBUTING.md).
-[ATTRIBUTION.md](ATTRIBUTION.md) · [SECURITY.md](SECURITY.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 CHANGED Viewed

@@ -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 CHANGED Viewed

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