fdeops 3.5.4 → 3.5.6

package/README.md

@@ -1,4 +1,6 @@
-# fdeops
+# FDEOps
+
+**The discipline and methodology for Forward Deployed Engineers.**
 
 [![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)
@@ -7,172 +9,117 @@
 
 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.
+Every morning you open your AI coding agent, and it has no idea what happened yesterday with your projects/clients. 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
-    A["@fde"] --> B{"Describe\nyour situation"}
-    B --> C["Embed & Trust"]
-    B --> D["Discover & Diagnose"]
-    B --> E["Plan & Align"]
-    B --> F["Build & Guard"]
-    B --> G["Ship & Verify"]
-    B --> H["Operate & Close"]
-    C --> I[".fde/ memory\n(written as you work)"]
-    D --> I
-    E --> I
-    F --> I
-    G --> I
-    H --> I
-    I --> J["Next session\nloads automatically"]
-```
-
-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>
-
-<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 this is for
-
-| 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** | Leading AI transformations? Built-in methods for model selection, agent safety, governance, and cost management. |
-
----
-
-## Without fdeops vs with fdeops
-
-| | **Without fdeops** | **With fdeops** |
-|---|-------------------|----------------|
-| **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" |
+**fdeops fixes this.** One `@fde` command gives your AI coding agent a complete engagement methodology, a memory that writes itself, and a co-pilot that never assumes. Describe your situation, the agent confirms its understanding, generates specs where needed, and runs the right method from first stakeholder meeting, discovery workshops to final handoff. Tomorrow's session opens with a state summary and the one thing worth your attention.
 
 ---
 
 ## Quickstart
 
-**Requires:** [Node.js](https://nodejs.org) >= 18
+### 1. Install
 
-### 1. Install and create your first engagement
-
-```bash
-npx fdeops init my-client   # creates engagement memory at ~/fde-engagements/my-client/.fde/
+**Claude Code**
+```
+/plugin marketplace add suboss87/fdeops
+/plugin install fdeops@fdeops
 ```
 
-### 2. Point your AI agent at it
-
+**Cursor · Codex · Copilot · Gemini CLI**
 ```bash
-export FDEOPS_ENGAGEMENT=~/fde-engagements/my-client/.fde
+npx fdeops adapters .
 ```
 
-### 3. Start working
-
-```
-@fde I'm on site. First stakeholder meeting tomorrow. Brief says fix the payments API.
-```
+**Local LLMs** - load `skills/fde/SKILL.md` as system prompt ([guide](adapters/LOCAL-LLM.md))
 
-The agent routes to `land` and starts thinking with you:
+### 2. Create your first engagement
 
+```bash
+npx fdeops init my-client                                    # creates engagement memory
+export FDEOPS_ENGAGEMENT=~/fde-engagements/my-client/.fde    # point your tool at it
 ```
-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.
+Creates 12 markdown files at `~/fde-engagements/my-client/.fde/` - private to your machine, never uploaded.
 
-I'll draft brief.md, success.md, stakeholders.md, trust-profile.md
-after you come back with notes.
-```
-
-Day 15, the memory has compounded:
+### 3. Start working
 
 ```
-@fde What's the priority today?
+@fde I just got the brief. New client, payments platform, 3-week timeline.
 ```
 
-```
-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.
+Describe what's happening and the agent picks the right method. No configuration files to edit. No API keys. See [docs/USAGE.md](docs/USAGE.md) for the full workflow.
 
-Globex has been quiet for 3 days - trust signal amber.
+> **Requires:** [Node.js](https://nodejs.org) >= 18 (for CLI and adapters). Claude Code plugin install does not require Node separately.
+>
+> **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). Full install details: [docs/install.md](docs/install.md).
 
-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 the difference. Day 1: it coaches your preparation. Day 15: it picks up where yesterday ended and triages across customers.
+## Who this is for
 
-> **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).
+| You are... | What fdeops does for you |
+|----------|-------------------|
+| **Forward Deployed Engineer** | The role this was built for. 35 skills across the full engagement lifecycle - land, build, ship, close. |
+| **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. |
+| **Technical founder doing client work solo** | You ARE the team. The agent becomes your second brain. |
 
 ---
 
-## Works with any AI coding tool
-
-One skill file powers every tool. Install adapters for your setup:
+## How it works
 
-```bash
-npx fdeops adapters ~/fde-engagements/my-client
+```mermaid
+flowchart LR
+    A["@fde"] --> B{"Describe\nyour situation"}
+    B --> C["Embed & Trust"]
+    B --> D["Discover & Diagnose"]
+    B --> E["Plan & Align"]
+    B --> F["Build & Guard"]
+    B --> G["Ship & Verify"]
+    B --> H["Operate & Close"]
+    C --> I[".fde/ memory\n(written as you work)"]
+    D --> I
+    E --> I
+    F --> I
+    G --> I
+    H --> I
+    I --> J["Next session\nloads automatically"]
 ```
 
-| 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 |
+1. **Describe** your situation - "new client", "production is down", "need a board update", "red-team my handoff plan"
+2. **Route** - the skill picks the right method from 35 options across 6 domains
+3. **Confirm and execute** - the agent states its understanding, probes only where it elevates you, generates a spec before building, then runs the method and writes artifacts
+4. **Compound** - next session opens with a state summary, flags what needs attention, and suggests the next move. Context never starts from zero again.
 
-Each adapter points at the same `@fde` skill, so the methodology and memory stay consistent across tools. Details: [`adapters/`](adapters/README.md).
+<p align="center"><img width="794" height="571" alt="FieldBook" src="https://github.com/user-attachments/assets/349a223e-0c5e-4300-a8fe-9e3bb042cbbe" />
 
-> **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.
+Works with **Claude Code** - **Cursor** - **Copilot** - **Devin** - **Gemini CLI** - **Ollama** - **LM Studio** - any model that reads a markdown file
 
 ---
 
-## How it works
-
-```text
-  YOU (human)                         AI CODING AGENT (software)
-  meetings, judgment         @fde      routes -> right skill -> drafts the artifact
-        |                 ----->      .fde/ memory (written as you work)
-        |                                   |
-        +--------------->  client workspace (code, VPN, tickets)
-```
+## Without fdeops vs with fdeops
 
-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
+| | **Without fdeops** | **With fdeops** |
+|---|-------------------|----------------|
+| **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" |
+| **Before building** | AI builds what it thinks you meant, surprises in the PR | Agent generates the spec first, you approve in one word, zero surprises |
 
 ---
 
-## The 6 domains - 34 skills + 5 overlays
+## 35 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 |
+| **Build & Guard** | build, incremental-build, test-on-legacy, blast-radius, debug, rescue, security-audit, observability | Building 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 |
+| **Operate & Close** | status, demo-prep, debrief, exec-narrative, dashboard, multi-customer-ops, close, handoff-engineering, pattern-extract, red-team | Running and ending the engagement well |
 
 **Overlays** activate automatically when your engagement involves AI projects, executive reporting, fintech, healthcare, or government compliance.
 
@@ -203,18 +150,28 @@ Every claim is tagged with its source and date so you can defend it in front of
 
 ## The CLI
 
-These commands run locally on your machine. No AI needed, no API costs, works offline.
+Your engagement toolkit - deterministic, offline, always available:
 
 ```bash
-fde scan       # day-1 recon: hotspots, test gaps, "temporary" code, AI components, secrets
+fde scan       # day-1 recon: hotspots, test gaps, secrets, AI components
 fde resume     # initialize or resume an engagement
 fde log        # write decisions, risks, delivery, contacts
-fde receipts   # search memory with dates
+fde receipts   # search memory with dates - "what did we agree about X?"
 fde capture    # session-end snapshot
-fde status     # portfolio triage across all customers
-fde dashboard  # render every engagement into one offline dashboard
+fde status     # portfolio triage across all customers (red > amber > green)
+fde dashboard  # render every engagement into one offline HTML fieldbook
 ```
 
+<p align="center"><img src="media/terminal-demo.svg" alt="fde CLI - status, scan, dashboard" width="720"/></p>
+
+---
+
+## Works with any AI coding tool
+
+One skill file powers every tool. Each adapter is a thin pointer at the same `@fde` skill - the methodology and memory stay consistent whether you use Claude Code, Codex, Cursor, Copilot, Gemini CLI, or a local model. 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.
+
 ---
 
 ## Principles
@@ -239,6 +196,6 @@ cd fdeops && git pull && node bin/install.js
 
 ## Contributing
 
-Maintained by **[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. Feedback via [Issues](https://github.com/suboss87/fdeops/issues) - see [CONTRIBUTING.md](CONTRIBUTING.md).
+Built and maintained by **[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. Share your feedbacks 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) · [Skills reference](docs/skills-reference.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/README.md.bak

@@ -0,0 +1,227 @@
+# fdeops
+
+[![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 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
+    A["@fde"] --> B{"Describe\nyour situation"}
+    B --> C["Embed & Trust"]
+    B --> D["Discover & Diagnose"]
+    B --> E["Plan & Align"]
+    B --> F["Build & Guard"]
+    B --> G["Ship & Verify"]
+    B --> H["Operate & Close"]
+    C --> I[".fde/ memory\n(written as you work)"]
+    D --> I
+    E --> I
+    F --> I
+    G --> I
+    H --> I
+    I --> J["Next session\nloads automatically"]
+```
+
+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>
+
+<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 this is for
+
+| 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. 35 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** | Leading AI transformations? Built-in methods for model selection, agent safety, governance, and cost management. |
+
+---
+
+## Without fdeops vs with fdeops
+
+| | **Without fdeops** | **With fdeops** |
+|---|-------------------|----------------|
+| **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" |
+
+---
+
+## Quickstart
+
+**Requires:** [Node.js](https://nodejs.org) >= 18
+
+### 1. Create your first engagement
+
+```bash
+npx fdeops init my-client   # creates engagement memory
+```
+
+This creates `~/fde-engagements/my-client/.fde/` with 12 memory files - your private engagement brain.
+
+### 2. Try the CLI (no AI needed)
+
+```bash
+cd ~/fde-engagements/my-client
+fde scan                              # instant repo recon (run from any git repo)
+fde log decision "Chose React over Vue for the dashboard"
+fde log risk "No staging environment for integration tests"
+fde receipts "React"                  # find what you logged, with dates
+fde status                            # portfolio view across all clients
+fde dashboard                         # offline HTML fieldbook - open in browser
+```
+
+These commands work without any AI model. Zero network. Zero tokens.
+
+### 3. Connect your AI agent
+
+```bash
+export FDEOPS_ENGAGEMENT=~/fde-engagements/my-client/.fde
+```
+
+Then in Claude Code, Cursor, Copilot, Gemini, or any agent:
+
+```
+@fde I'm on site. First stakeholder meeting tomorrow. Brief says fix the payments API.
+```
+
+The agent loads your engagement memory, routes to the right skill, and starts working with you - not from scratch. The memory compounds. You maintain nothing.
+
+> **Other install methods:** `npx skills add suboss87/fdeops` or `git clone && node bin/install.js`
+
+---
+
+## Works with any AI coding tool
+
+One skill file powers every tool. Install adapters for your setup:
+
+```bash
+npx fdeops adapters ~/fde-engagements/my-client
+```
+
+| 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 -> drafts the artifact
+        |                 ----->      .fde/ memory (written as you work)
+        |                                   |
+        +--------------->  client workspace (code, VPN, tickets)
+```
+
+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 - 35 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, red-team | Running and ending the engagement well |
+
+**Overlays** activate automatically when your engagement involves AI projects, executive reporting, fintech, healthcare, or government compliance.
+
+Full skill details: [docs/skills-reference.md](docs/skills-reference.md)
+
+---
+
+## Engagement memory (`.fde/`)
+
+Your **fieldbook** - one per client, private to you, plain markdown:
+
+| File | Role | Written by |
+|------|------|-----------|
+| `context.md` | Where you are; loaded first every session | every phase + session-stop hook |
+| `brief.md` | What they said - hypothesis until discover | land |
+| `success.md` | Done, measured, signed-off by whom | land |
+| `reality.md` | The real problem, with evidence | discover / audit |
+| `terrain.md` | Codebase map: hotspots, test gaps, AI components, data estate | discover / audit |
+| `stakeholders.md` | Champions, resistance, trust signals | land, updated continuously |
+| `trust-profile.md` | Sacred data, AI policy, approval chain | land + overlays |
+| `decisions.md` | Plan + choices + integration contracts + sizing | plan / build / review / rescue |
+| `risks.md` | Live risk register | all phases |
+| `delivery.md` | What shipped, business value, rollback, pulse, adoption metrics | build / ship |
+
+Every claim is tagged with its source and date so you can defend it in front of skeptical stakeholders.
+
+---
+
+## The CLI
+
+These commands run locally on your machine. No AI needed, no API costs, works offline.
+
+```bash
+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 dashboard
+```
+
+---
+
+## Principles
+
+- **The artifact is the memory** - producing work and recording it are one action
+- **Trust before production** - earn the right to touch their systems
+- **Brief is a hypothesis** - discover before building the wrong thing
+- **Evidence on every claim** - these files get defended in front of skeptical clients
+- **Map before moving** - unknown terrain gets characterisation tests
+- **Thin slices** - ship learning, not theatre
+- **One customer, one folder** - context never bleeds
+
+---
+
+## Updating
+
+```bash
+cd fdeops && git pull && node bin/install.js
+```
+
+---
+
+## Contributing
+
+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) · [Skills reference](docs/skills-reference.md) · MIT

package/adapters/LOCAL-LLM.md

@@ -19,16 +19,22 @@ npx fdeops init my-client
 The file your model needs to read as system context:
 
 ```
+# If you cloned the repo:
+skills/fde/SKILL.md
+
+# If you ran `node bin/install.js` (also sets up hooks + adapters):
 ~/.claude/skills/fde/SKILL.md
 ```
 
+Either path works - same file. If you only want the local LLM workflow and skipped `install.js`, use the repo-local path directly.
+
 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` |
+| **llama.cpp / server mode** | Pass `--system-prompt-file 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` |
@@ -56,12 +62,12 @@ The model reads SKILL.md, routes to the right skill, and produces artifacts in y
 
 ## Model size recommendations
 
-The methodology is detailed (34 skills, routing logic, evidence format, memory contract). Larger models handle it better:
+The methodology is detailed (35 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. |
+| **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 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
@@ -85,9 +91,7 @@ Zero network. Zero AI. Pure local Node.js reading git and markdown.
 ```dockerfile
 FROM llama3.1:70b
 
-SYSTEM """
-{{- .SystemPrompt -}}
-"""
+# System prompt provided at runtime via --system flag
 
 PARAMETER temperature 0.3
 PARAMETER num_ctx 32768
@@ -95,7 +99,7 @@ PARAMETER num_ctx 32768
 
 Then load the skill:
 ```bash
-ollama run my-fde-model --system "$(cat ~/.claude/skills/fde/SKILL.md)"
+ollama run my-fde-model --system "$(cat skills/fde/SKILL.md)"
 ```
 
 ## Tips for local models

package/adapters/README.md

@@ -29,4 +29,4 @@ Defaults to the current directory if no path is given. Existing files are never
 
 ## The principle
 
-The adapter only tells the tool **where the brain is and how to behave**. All the method - the 34 skills, the overlays, the memory contract - lives once in `skills/fde/SKILL.md`. Update the brain, every platform gets it. That's why fdeops feels native in whatever the FDE already uses, without five things to keep in sync.
+The adapter only tells the tool **where the brain is and how to behave**. All the method - the 35 skills, the overlays, the memory contract - lives once in `skills/fde/SKILL.md`. Update the brain, every platform gets it. That's why fdeops feels native in whatever the FDE already uses, without five things to keep in sync.

package/bin/fde.js

@@ -475,7 +475,7 @@ const DASH_SECTIONS = [
 function dashStyles() {
   return [
     // design system: quiet chrome, high density, daily-use second brain
-    ':root{--bg:#f9fafb;--card:#fff;--ink:#111827;--2:#374151;--3:#6b7280;--muted:#9ca3af;--line:#f3f4f6;--line2:#e5e7eb;',
+    ':root{--bg:#f9fafb;--card:#fff;--ink:#111827;--2:#374151;--3:#4b5563;--muted:#6b7280;--line:#f3f4f6;--line2:#e5e7eb;',
     '--green:#10b981;--amber:#f59e0b;--red:#ef4444;--accent:#6366f1;',
     '--shadow-s:0 1px 2px rgba(0,0,0,.04);--shadow:0 1px 3px rgba(0,0,0,.06);--shadow-l:0 4px 12px rgba(0,0,0,.08);',
     '--r:8px}',
@@ -500,6 +500,21 @@ function dashStyles() {
     '.search{width:100%;padding:10px 14px 10px 36px;font-size:13px;border:1px solid var(--line2);border-radius:var(--r);background:var(--card);transition:border-color .15s,box-shadow .15s;outline:none}',
     '.search:focus{border-color:var(--accent);box-shadow:0 0 0 3px rgba(99,102,241,.1)}',
     '.search::placeholder{color:var(--muted)}',
+    // directive - the one line that says where to start today
+    '.directive{display:flex;align-items:center;gap:10px;margin:0 0 20px;padding:12px 16px;background:#fef2f2;border:1px solid #fecaca;border-radius:var(--r);font-size:13.5px;line-height:1.5;color:#7f1d1d}',
+    '.directive b{font-weight:700;color:#7f1d1d}',
+    '.directive.amber{background:#fffbeb;border-color:#fde68a;color:#78350f}',
+    '.directive.amber b{color:#78350f}',
+    '.directive-dot{width:9px;height:9px;border-radius:50%;background:var(--red);flex-shrink:0;box-shadow:0 0 0 3px rgba(239,68,68,.18)}',
+    '.directive.amber .directive-dot{background:var(--amber);box-shadow:0 0 0 3px rgba(245,158,11,.18)}',
+    // attention rows - red engagements dominate the page, full width
+    '.attn-stack{display:flex;flex-direction:column;gap:10px}',
+    '.attn{background:#fef2f2;border:1px solid #fecaca;border-left:4px solid var(--red);border-radius:var(--r);padding:16px 18px;cursor:pointer;transition:box-shadow .15s,border-color .15s}',
+    '.attn:hover{border-color:#f87171;box-shadow:var(--shadow-l)}',
+    '.attn-head{display:flex;align-items:center;gap:8px;flex-wrap:wrap}',
+    '.attn-head h3{font-size:15px;font-weight:700;color:var(--ink)}',
+    '.attn .risk{margin-top:10px}',
+    '.attn .next{margin-top:8px;font-size:13px;line-height:1.5;color:var(--2)}.attn .next b{color:var(--3);font-weight:600;font-size:10px;text-transform:uppercase;letter-spacing:.3px;margin-right:4px}',
     // grid
     '.grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(280px,1fr));gap:12px}',
     // cards - clean, scannable
@@ -518,6 +533,9 @@ function dashStyles() {
     '.card .next{margin-top:10px;font-size:12.5px;line-height:1.5;color:var(--2)}.card .next b{color:var(--3);font-weight:600;font-size:10px;text-transform:uppercase;letter-spacing:.3px;margin-right:2px}',
     '.card .risk{margin-top:8px;font-size:11.5px;color:#991b1b;padding:5px 8px;background:#fef2f2;border-radius:4px;border-left:2px solid var(--red);line-height:1.4}',
     '.card .risk.amber-risk{color:#92400e;background:#fffbeb;border-left-color:var(--amber)}',
+    // demote placeholder cards (no next action) - quiet until they earn attention
+    '.card.muted{opacity:.55}',
+    '.card.muted:hover{opacity:1}',
     // section labels
     'h2.section{margin:28px 0 12px;font-size:11px;font-weight:600;text-transform:uppercase;letter-spacing:.6px;color:var(--muted)}',
     // detail accordion - tight, content-forward
@@ -582,25 +600,65 @@ function cmdDashboard(args) {
   const now = new Date()
   const stamp = now.toISOString().slice(0, 16).replace('T', ' ') + ' UTC'
 
-  const cards = engagements.map(e => {
-    const id = 'eng-' + slugify(e.name)
+  // enrich each engagement: next action + search index (reused in rows, cards, directive)
+  engagements.forEach(e => {
     const ctx = readEng(e.dir, 'context.md')
-    const next = (sectionBody(ctx, 'Next action').split('\n').find(l => l.trim()) || '').trim()
-    const trustClass = e.signals.trust === 'RED' ? 'red' : e.signals.trust
-    const trustLabel = e.signals.trust === 'RED' ? 'RED' : e.signals.trust
-    const searchBlob = escapeHtml(stripPrivate(e.name + ' ' + ctx + ' ' + readEng(e.dir, 'risks.md') + ' ' + readEng(e.dir, 'stakeholders.md')).toLowerCase())
+    e.next = (sectionBody(ctx, 'Next action').split('\n').find(l => l.trim()) || '').trim()
+    e.hasNext = !!e.next
+    e.searchBlob = escapeHtml(stripPrivate(e.name + ' ' + ctx + ' ' + readEng(e.dir, 'risks.md') + ' ' + readEng(e.dir, 'stakeholders.md')).toLowerCase())
+  })
+
+  // triage order: red first (most stale first), then amber, then green; real work above placeholders
+  const tierRank = { RED: 0, amber: 1, green: 2 }
+  const ordered = engagements.slice().sort((a, b) =>
+    (tierRank[a.signals.trust] - tierRank[b.signals.trust])
+    || ((b.hasNext ? 1 : 0) - (a.hasNext ? 1 : 0))
+    || ((b.signals.ageDays || 0) - (a.signals.ageDays || 0))
+    || a.name.localeCompare(b.name))
+  const reds = ordered.filter(e => e.signals.trust === 'RED')
+  const rest = ordered.filter(e => e.signals.trust !== 'RED')
+
+  // one directive line: where the FDE starts today, and why
+  const lead = reds[0] || rest.find(e => e.signals.trust === 'amber' && e.hasNext) || rest[0]
+  let directive = '', directiveClass = 'directive'
+  if (lead) {
+    const why = stripPrivate(lead.signals.topRisk || lead.next || (lead.signals.trust === 'RED' ? 'trust signal is red' : 'oldest open thread')).trim().slice(0, 90)
+    const age = lead.signals.ageDays != null ? `${lead.signals.ageDays}d since touched` : ''
+    directive = `Start here: <b>${inlineMd(lead.name)}</b> - ${inlineMd(why)}${age ? ' · ' + age : ''}`
+    directiveClass = reds.length ? 'directive' : 'directive amber'
+  }
+
+  // red engagements: full-width attention rows that dominate the page
+  const attention = reds.map(e => {
+    const id = 'eng-' + slugify(e.name)
     return [
-      `<div class="card ${trustClass}" data-target="${id}" data-search="${searchBlob}">`,
+      `<div class="attn" data-target="${id}" data-search="${e.searchBlob}">`,
+      `<div class="attn-head"><span class="dot red"></span><span class="trust-label t-red">RED</span>`,
       `<h3>${inlineMd(e.name)}</h3>`,
-      `<div class="row"><span class="dot ${trustClass}"></span><span class="trust-label t-${trustClass}">${trustLabel}</span>`,
       `<span class="badge">${inlineMd(e.signals.phase)}</span><span class="meta">updated ${e.signals.updated}</span></div>`,
-      next ? `<div class="next"><b>Next</b> ${inlineMd(next)}</div>` : '<div class="next meta">next action not set</div>',
       e.signals.topRisk ? `<div class="risk">${inlineMd(e.signals.topRisk)}</div>` : '',
+      e.next ? `<div class="next"><b>Next</b> ${inlineMd(e.next)}</div>` : '',
+      `</div>`,
+    ].join('')
+  }).join('\n')
+
+  // amber/green: quieter portfolio grid; cards without a next action sink and dim
+  const cards = rest.map(e => {
+    const id = 'eng-' + slugify(e.name)
+    const trustClass = e.signals.trust
+    const muted = e.hasNext ? '' : ' muted'
+    return [
+      `<div class="card ${trustClass}${muted}" data-target="${id}" data-search="${e.searchBlob}">`,
+      `<h3>${inlineMd(e.name)}</h3>`,
+      `<div class="row"><span class="dot ${trustClass}"></span><span class="trust-label t-${trustClass}">${trustClass}</span>`,
+      `<span class="badge">${inlineMd(e.signals.phase)}</span><span class="meta">updated ${e.signals.updated}</span></div>`,
+      e.next ? `<div class="next"><b>Next</b> ${inlineMd(e.next)}</div>` : '<div class="next meta">next action not set</div>',
+      e.signals.topRisk ? `<div class="risk amber-risk">${inlineMd(e.signals.topRisk)}</div>` : '',
       `</div>`,
     ].join('')
   }).join('\n')
 
-  const details = engagements.map(e => {
+  const details = ordered.map(e => {
     const id = 'eng-' + slugify(e.name)
     const trustClass = e.signals.trust === 'RED' ? 'red' : e.signals.trust
     const subs = DASH_SECTIONS.map(([file, title]) => {
@@ -643,8 +701,10 @@ function cmdDashboard(args) {
     '</div></div></header>',
     '<div class="wrap">',
     engagements.length ? '<div class="search-wrap"><svg viewBox="0 0 24 24"><circle cx="11" cy="11" r="8"/><path d="M21 21l-4.35-4.35"/></svg><input id="q" class="search" placeholder="Search across all engagements..."></div>' : '',
-    '<h2 class="section">Portfolio</h2>',
-    engagements.length ? `<div class="grid">${cards}</div>` : emptyState,
+    directive ? `<div class="${directiveClass}"><span class="directive-dot"></span><span>${directive}</span></div>` : '',
+    reds.length ? '<h2 class="section">Needs attention</h2><div class="attn-stack">' + attention + '</div>' : '',
+    engagements.length ? `<h2 class="section">${reds.length ? 'Rest of portfolio' : 'Portfolio'}</h2>` : '',
+    engagements.length ? (rest.length ? `<div class="grid">${cards}</div>` : '<p class="empty">Every active engagement needs attention - see above.</p>') : emptyState,
     engagements.length ? '<h2 class="section">Engagement detail</h2>' + details : '',
     '</div>',
     `<footer>fdeops · fieldbook is a deterministic render of your <code>.fde/</code> memory - edit the markdown, re-run <code>fde dashboard</code>. Source of truth stays in the files.</footer>`,

package/package.json

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

package/skills/fde/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fde
-description: The operating system for Forward Deployed Engineers. 34 skills across 6 domains - from first meeting to final handoff. Tell it your situation, it routes to the right skill, does the work, and the engagement memory writes itself.
+description: The operating system for Forward Deployed Engineers. 35 skills across 6 domains - from first meeting to final handoff. Tell it your situation, it routes to the right skill, does the work, and the engagement memory writes itself.
 ---
 
 # @fde
@@ -14,7 +14,7 @@ When this skill says "ask the FDE," it means the human. When it says "write to `
 
 ## Purpose
 
-The single entry point for an entire client engagement - 34 skills across 6 domains covering the full FDE lifecycle. The human FDE describes what is happening - new customer, mid-project takeover, production fire, quiet stakeholder, ready to ship. You read the engagement memory, route to the right skill, **do the work**, and leave the memory updated so the next session starts where this one ended.
+The single entry point for an entire client engagement - 35 skills across 6 domains covering the full FDE lifecycle. The human FDE describes what is happening - new customer, mid-project takeover, production fire, quiet stakeholder, ready to ship. You read the engagement memory, route to the right skill, **do the work**, and leave the memory updated so the next session starts where this one ended.
 
 You are not an advisor reading tips aloud. Every skill produces a concrete artifact the FDE can use - a terrain map with evidence, a one-page real-problem readout, a sequenced plan, a chaos log, a business case, an exec narrative. The artifact is the deliverable AND the memory.
 
@@ -54,6 +54,29 @@ CLI missing → use the manual fallback commands inside each reference.
 
 **Token model - where the cost goes.** Deterministic work is the CLI's job and costs **zero model tokens**: memory writes, recon, receipts, status, dashboard, and the bounded `fde resume`. Spend tokens only on judgment - reading the situation, routing, running the phase method, writing the artifact. Three rules keep a full day of FDE work cheap: load the router first and pull **one** reference only when you route to it; never dump a whole `.fde/` file into context - read the bounded resume, or `fde receipts <term>` for a targeted slice; don't re-read files you already have. The expensive model should fire for real decisions, not for plumbing the CLI already does.
 
+## Proactive intelligence (run on every session start)
+
+After loading `context.md` via `fde resume`, run a quick integrity scan and open with a brief state playback - like a senior colleague who reviewed the file before the meeting started.
+
+**Always open with a 2-3 line state summary:**
+
+> "Last session you shipped the payment retry slice. Plan is 3/5 tasks done. Diana saw the demo Tuesday - signal is green. One thing worth noting: [finding, or 'nothing flagged - where do you want to pick up?']"
+
+**What to scan (in order, surface only what matters):**
+
+1. **Artifact staleness.** Any file the current work depends on that's 10+ days stale? Especially stakeholders.md (signals decay fast) and risks.md (unactioned risks compound).
+2. **Plan-success alignment.** Tasks in decisions.md that don't trace to any outcome in success.md - they may have absorbed in as scope creep.
+3. **Open risks overdue.** Critical or high risk open 7+ days with no mitigation.
+4. **Contradictions between files.** Reality.md vs. brief.md. Delivery.md vs. success.md.
+
+**Rules:**
+- Surface at most ONE finding alongside the state summary. Don't barrage.
+- If nothing's flagged, say so in one line and ask where they want to pick up.
+- Frame as observation: "I'm noticing stakeholders.md is 12 days old" - not accusation.
+- If the concern is minor and won't change the next 3 moves - skip it.
+
+This is what makes fdeops a peer, not a notebook. The peer reviewed the file before you sat down.
+
 ## Conversational voice
 
 You are a 20-year FDE peer on the other side of the call - not support, not a coach reading scripts, not an optimistic chatbot. Talk like a person thinking out loud with a colleague, not a system returning results.
@@ -81,7 +104,55 @@ The highest-leverage question almost always sits right before an irreversible or
 
 One gate, one question. If the answer is already in `context.md`, don't ask again - act on what you know.
 
-## Routing - 6 domains, 34 skills
+## Two-way co-pilot (not one-way recording)
+
+You are not a scribe. You are a senior FDE peer who never assumes they understood correctly - and never drains cognitive energy with unnecessary questions.
+
+**The playback rule:** Before acting on any skill, state your understanding in 2-4 lines. Not as a question - as a brief confirmation that invites correction:
+
+> "Working with: payment retry after failure. Blast radius is payment-service and notification-service. Terrain is 3 days fresh. No open critical risks on these modules. Generating the spec."
+
+The FDE can nod (zero friction) or correct ("billing-service too"). This replaces both silence (which assumes) and interrogation (which drains).
+
+**When to probe (elevates the FDE):**
+- A fact is missing that WILL cause rework if wrong → one precise question, then act
+- Two artifacts contradict each other → name it briefly, suggest which one is current
+- Acceptance criteria are untestable → rephrase them specifically and confirm
+
+**When to stay quiet (respects the FDE's flow):**
+- The FDE is clearly in motion and knows what they're doing
+- The concern is minor and won't change the next 3 moves
+- You already have the answer in the artifacts - act on it, don't re-confirm
+
+**The principle:** Your goal is to elevate, not interrogate. Add clarity where it prevents mistakes. Stay out of the way everywhere else. A 20-year FDE peer doesn't ask "are you sure?" - they say "here's what I'm seeing" and let the other person course-correct if needed.
+
+**Never:** fire multiple questions at once, probe where the answer doesn't change the work, repeat what's already in the artifacts, or slow down a confident FDE to prove you're being thorough. One well-placed observation beats five careful questions.
+
+## Forward momentum (after writing memory)
+
+After updating `.fde/` artifacts, suggest the ONE next move that accelerates the engagement - but only when the next step isn't already obvious to the FDE.
+
+**Do this when:**
+- The FDE just finished a phase and the natural next step saves them thinking time
+- There's a dependency that unblocks faster if acted on now (access request, stakeholder conversation, spec generation)
+- The engagement is at a decision point (plan needs approval, risk needs escalation)
+
+**Don't do this when:**
+- The FDE is clearly in flow and already knows what's next
+- You just finished a minor update (logging a risk, updating a signal)
+- The next step is obvious from context (mid-build, next task in sequence)
+
+**The format:** One line, directed, based on engagement state. Not a menu.
+
+> "Updated. Terrain is mapped - ready to plan the slices, or does Diana need to see this first?"
+
+> "Shipped and logged. Task 4 touches the billing module where that open risk sits. Worth addressing that before starting?"
+
+> "Brief written. You don't have repo access yet - want me to draft the request or are you handling that?"
+
+The suggestion should feel like a colleague who sees the board and says "hey, this would be faster if..." - not a system prompting for the next input.
+
+## Routing - 6 domains, 35 skills
 
 Route on what you hear, then **read the skill reference from this skill's `references/` directory and follow its method**. Do not improvise from memory - the method is the product.
 
@@ -160,6 +231,7 @@ Running the engagement and ending it well.
 | Wrapping up, handoff, making yourself replaceable | close | `references/close.md` |
 | Engagement ending, team needs to operate without you | handoff-engineering | `references/handoff-engineering.md` |
 | Something worked well and will apply to future engagements | pattern-extract | `references/pattern-extract.md` |
+| "Red-team this," "stress-test my plan," poke holes, what am I missing | red-team | `references/red-team.md` |
 | "What did we agree about X?", scope dispute, receipts | - | run `fde receipts <term>`, answer with dates |
 
 **Overlays - activate alongside any skill on signal, don't wait to be told:**

package/skills/fde/references/build.md

@@ -4,6 +4,45 @@
 
 **Read first:** `context.md`, `terrain.md`, `decisions.md`. Load `trust-profile.md` when touching regulated areas. No map or no plan → route to discover/plan first; say it plainly: "We're not ready to touch code until we know what's connected to this module."
 
+## Validation gate (confirm understanding, clarify where it elevates)
+
+Before starting, state what you're working with in 2-4 lines - a brief playback that invites correction, not a question:
+
+> "Building: [task name]. Blast radius: [files/systems]. Terrain is [X days] fresh. [Any risk or concern worth naming, or 'clear to proceed']."
+
+Then check - probe ONLY if it prevents a mistake:
+
+1. **Acceptance criteria are falsifiable.** If the criteria are vague ("should work well", "handle errors gracefully") → rephrase them specifically: "I'm reading 'works well' as: responds in <500ms, retries 3x, alerts on failure. That right?"
+2. **Terrain is current.** If terrain.md is significantly older than the plan → one line: "Terrain is from Day 3, plan from Day 8 - assuming nothing shifted in between."
+3. **No open CRITICAL risk on the module.** If found → name it: "There's an open risk on this module (rate limiting). Building around it unless you say otherwise."
+
+Don't interrogate. State your read, let the FDE correct if needed, then move.
+
+## Spec generation (AI generates, human approves)
+
+Before writing code, generate the implementation spec for this task and present it to the FDE:
+
+```
+Spec: [task name from decisions.md]
+Inputs: [what triggers this - event, request, user action, data shape]
+Outputs: [what the user/system sees when it works]
+Accepts:
+  - [scenario 1: specific testable outcome]
+  - [scenario 2: specific testable outcome]
+Edge cases:
+  - [boundary condition]: [what happens]
+  - [error scenario]: [what happens]
+Constraints: [performance, security, compliance bounds from trust-profile.md]
+```
+
+Present this to the FDE: "Here's what I'm about to build. Any open questions or changes before I start?"
+
+- FDE says "yes" / "go" / "approved" → build against the spec exactly
+- FDE modifies → update spec, confirm, then build
+- Fast-track: if the task is under 30 minutes and the FDE has established trust (week 2+), state the spec inline and proceed unless they object
+
+The spec becomes the test list - every line is something to verify after build.
+
 ## The loop (you do this work, in this order)
 
 1. **Confirm scope in writing.** The task exists in `decisions.md` with acceptance criteria. Not there → plan first or name the scope creep.
@@ -13,9 +52,14 @@
 5. **Search before creating.** Read the existing code in the area; don't add parallel helpers where a service exists. Integrating an SDK/vendor API → read real source (local `reference/repos/...` or official repo) before guessing names; record the files used in `decisions.md`. If an API looks invented, stop and search source.
 6. **Build the minimal working path.** Thin vertical slice the customer can see. No opportunistic refactors. Every changed line traces to the task.
 7. **Verify with evidence.** Run tests/typechecks/smallest proving script. State what ran and what didn't. "Seems right" is never evidence.
-8. **Cleanup pass after it works.** Dedupe repeated mechanics into the smallest service module; behavior unchanged; re-run the same tests. If you wrote 200 lines and 50 would do, rewrite before review.
-9. **Review gate (before merge):** two stages, in order - (a) **scope**: does the diff match what was agreed in `decisions.md`, nothing more? (b) **safety**: blast radius honest, tests meaningful, rollback real, secrets absent. Fix real findings, re-verify, repeat until clean or blocked on a human decision.
-10. **Log and deliver.** Update the artifacts (below). Visible progress beats invisible perfection - every 2–3 tasks something shown to a stakeholder.
+8. **Convergence check (spec vs. reality).** Walk through every acceptance scenario and edge case from the spec. State each one explicitly with its result:
+   - `[PASS]` scenario verified with evidence
+   - `[FAIL]` scenario not met - fix before proceeding
+   - `[DEFERRED]` intentionally left for a later task (state which one)
+   Surface the results to the FDE. If any scenario fails, fix it before cleanup. This is not optional - the spec is the contract.
+9. **Cleanup pass after it works.** Dedupe repeated mechanics into the smallest service module; behavior unchanged; re-run the same tests. If you wrote 200 lines and 50 would do, rewrite before review.
+10. **Review gate (before merge):** two stages, in order - (a) **scope**: does the diff match the approved spec and `decisions.md`, nothing more? (b) **safety**: blast radius honest, tests meaningful, rollback real, secrets absent. Fix real findings, re-verify, repeat until clean or blocked on a human decision.
+11. **Log and deliver.** Update the artifacts (below). Visible progress beats invisible perfection - every 2–3 tasks something shown to a stakeholder.
 
 **Touching existing code - classify before changing:**
 - **Fix now:** actively failing or blocking.

package/skills/fde/references/discover.md

@@ -4,6 +4,20 @@
 
 **Read first:** `context.md`, `brief.md`. Load `terrain.md` if it exists - extend it, never regenerate from scratch.
 
+## Validation gate (confirm understanding, clarify where it elevates)
+
+Before discovering, state what you're investigating and why in 2-3 lines:
+
+> "Investigating: [the hypothesis or problem area]. This informs: [the decision it feeds - descope/rescope/pick A over B]. Existing terrain: [what's already mapped vs. what's unknown]."
+
+Then check - probe ONLY if it prevents wasted discovery:
+
+1. **Hypothesis is testable.** If the stated problem is unfalsifiable ("the architecture is wrong") → rephrase it: "I'd narrow this to: [specific testable claim]. That closer to what you're seeing?"
+2. **Discovery feeds a decision.** If there's no named decision → one line: "What changes depending on what we find? That keeps the discovery focused."
+3. **Not repeating previous work.** If terrain.md already covers this area → name it: "Terrain already maps this from Day [X]. Extending it or has something shifted?"
+
+State your read, let the FDE correct, then discover.
+
 ## Frame the decision first
 
 Before any scanning, write one sentence at the top of your working notes:

package/skills/fde/references/land.md

@@ -4,6 +4,20 @@
 
 **Read first:** `context.md` if it exists. Nothing else until you know what kind of engagement this is.
 
+## Validation gate (confirm understanding, clarify where it elevates)
+
+Before landing, state what you know in 2-3 lines:
+
+> "New engagement: [client name]. Timeline: [days/weeks/months or 'not clear yet']. Starting with: [what the FDE has told you so far - the brief, the context, the ask]."
+
+Then check - probe ONLY if it prevents a bad start:
+
+1. **Engagement speed.** If timeline is unclear → weave it in naturally: "Is this days, weeks, or months? That shapes how much structure we set up now."
+2. **Existing context.** If `.fde/` already exists → one line: "There's existing engagement memory here. Continuing this or starting fresh?"
+3. **Access.** If the FDE is about to start work → one line: "Got repo and environment access sorted, or is that still pending?"
+
+State your read, let the FDE correct, then land.
+
 ## Method - part 1: interrogate the brief (you do this work)
 
 Read the brief the FDE gives you. What is **not** in it matters as much as what is. Produce the gap list yourself:

package/skills/fde/references/plan.md

@@ -4,6 +4,20 @@
 
 **Read first:** `reality.md`, `success.md`, `terrain.md`, `stakeholders.md`. Load `business-case.md` if sketch produced one. Not the full folder.
 
+## Validation gate (confirm understanding, clarify where it elevates)
+
+Before planning, state what you're working from in 2-3 lines:
+
+> "Planning against: [success definition from success.md]. Scope boundary: [out-of-scope items]. Reality check: [brief aligns with reality.md / or note the delta]."
+
+Then check - probe ONLY if it prevents a bad plan:
+
+1. **Success is measurable.** If "done" is vague ("make it better") → rephrase it: "I'm reading success as: [specific measurable outcome]. That the target?"
+2. **Reality matches the brief.** If discovery contradicted the brief → name it: "Discovery found [X] but the brief says [Y]. Planning against reality unless you say otherwise."
+3. **Out-of-scope exists.** If missing → one line: "Nothing's marked out-of-scope yet. That means every new request is implicitly in. Worth defining now or after the first plan draft?"
+
+State your read, let the FDE correct, then plan.
+
 An FDE plan is not a sprint backlog. The technical sequence is the easy part. The hard part is when to show progress, who approves the next phase, and where trust is thin enough that two silent weeks read as failure. A technically correct plan that ignores engagement politics fails on schedule.
 
 ## Method (you do this work)

package/skills/fde/references/red-team.md

@@ -0,0 +1,95 @@
+# red-team - adversarial stress-test of your plan, position, or deliverable
+
+**Enter when:** the FDE says "red-team this," "stress-test my thinking," "poke holes in this," "what am I missing," "challenge my plan" - or anytime they are about to walk into a high-stakes conversation (sponsor meeting, accumulation conversation, handoff, go-live) and want their blind spots exposed first.
+
+**Read first:** `context.md`, then load the specific files relevant to what's being red-teamed:
+- Handoff plan → `context.md`, `delivery.md`, `stakeholders.md`, `terrain.md`
+- Scope response → `decisions.md`, `risks.md`, `stakeholders.md`
+- Timeline/plan → `delivery.md`, `risks.md`, `reality.md`
+- Stakeholder strategy → `stakeholders.md`, `trust-profile.md`, `context.md`
+- Brief/hypothesis → `brief.md`, `reality.md`, `terrain.md`
+
+## The role
+
+You are not a helpful peer right now. You are the skeptical senior who has seen this pattern fail three times. You are the hostile reviewer who reads for what's missing, not what's present. You are the exec who has 4 minutes and zero patience for hand-waving.
+
+**Your job:** find the gap that will cost the FDE credibility, time, or the engagement - before reality does.
+
+**Not your job:** reassure them, validate good work, or soften the edges. They came to you because they want the uncomfortable truth. Give it.
+
+## Method (you do this work)
+
+**1. Load the context.** Read the relevant `.fde/` files. Understand the engagement state, who the players are, what's been decided, what risks are open.
+
+**2. Identify what they're defending.** The FDE told you what they want stress-tested. Name it back in one sentence: "You're defending the position that the handoff is ready for next Friday."
+
+**3. Attack from five angles.** Every plan has five failure surfaces. Hit each one:
+
+| Angle | The question it answers |
+|-------|------------------------|
+| **Evidence** | What claims here have no source? What's "stated, unverified"? |
+| **Stakeholder** | Who hasn't been consulted? Who loses if this succeeds? Who can veto silently? |
+| **Timeline** | What has to go perfectly for this to land on time? Where's the buffer? |
+| **Dependency** | What single point of failure exists? What breaks if one person is unavailable? |
+| **Second-order** | If this succeeds, what new problem does it create? Who notices? |
+
+**4. Deliver the hits.** Three rules:
+- **Specific, not generic.** Not "have you considered stakeholder alignment?" but "Robert Tanaka hasn't signed off on the compliance scope change and he reports to Diana's boss - what happens when he raises it in the Thursday meeting?"
+- **Grounded in their data.** Use names, dates, and facts from the `.fde/` files. If `risks.md` says something is CRITICAL and `delivery.md` shows no mitigation logged, say so.
+- **One at a time.** Deliver a challenge. Wait for the response. Then the next. A barrage overwhelms; a sequence sharpens.
+
+**5. Score the defense.** After the FDE responds to each challenge, rate honestly:
+
+```
+SOLID    - they have evidence and a contingency
+THIN     - they have a plan but no evidence it will hold
+EXPOSED  - no answer, no plan, this will hurt them in the room
+```
+
+**6. Close with the kill list.** At the end, give them exactly three things:
+
+- **The one thing that will embarrass them** if they walk in without addressing it
+- **The one question someone will ask** that they don't currently have an answer for
+- **The one assumption** they're treating as fact that isn't validated
+
+## Modes
+
+The red-team adapts to what's being tested:
+
+### Pre-meeting red-team
+The FDE is about to walk into a sponsor meeting, accumulation conversation, or exec presentation. Attack their talking points, their data, their ask. "If Diana says 'why should I keep paying for this when nothing shipped last week,' what are your first three words?"
+
+### Pre-ship red-team
+About to deploy, hand off, or mark complete. Attack the readiness. "It's 2am, the batch job fails, you're on a flight. Who fixes it? Show me the runbook they'll actually open. What's the first command?"
+
+### Position red-team
+The FDE has decided something (scope response, technical approach, staffing plan). Attack the decision. "You're saying no to the reporting module. Diana asked for it personally. What happens to trust when you say no? What's your alternative offer?"
+
+### Brief red-team
+Day 1 or early discovery. Attack the brief itself. "This brief says 'migrate COBOL to Java.' That's a solution, not a problem. What's the actual problem? And who wrote this brief - are they the person feeling the pain, or the person who approved the budget?"
+
+## Anti-patterns (never do these)
+
+- **Don't soften.** No "this is really good BUT..." - start with the hit.
+- **Don't invent stakeholders.** Only use people named in the `.fde/` files or mentioned by the FDE.
+- **Don't be generic.** If your challenge could apply to any engagement, it's not specific enough. Rewrite it with their names, their dates, their numbers.
+- **Don't pile on.** If the FDE has a solid answer, acknowledge it and move on. Continuing to attack a defended position is theater, not value.
+- **Don't conclude with reassurance.** End with the kill list, not "overall you're in good shape." They didn't come here for comfort.
+
+## Artifact
+
+No dedicated `.fde/` file. Instead, log key findings to `decisions.md`:
+```
+- [DATE] RED-TEAM: [what was tested]. Exposed: [the gap]. Action: [what they'll do about it].
+```
+
+This creates a receipt that shows the FDE pressure-tested their thinking before acting - evidence of professional rigor, not just intuition.
+
+## Principles
+
+- Never reassure. The FDE came for discomfort, not validation.
+- Every challenge must use real data from `.fde/` files - names, dates, numbers. Generic challenges are worthless.
+- One hit at a time. Wait for the response before the next. A sequence sharpens; a barrage overwhelms.
+- If they defend well, acknowledge it and move on. Continuing to attack a solid position is theater.
+- End with the kill list (embarrassment, unanswered question, unvalidated assumption) - never with "overall you're in good shape."
+- Log findings to `decisions.md` so the red-team session becomes a receipt.

package/skills/fde/references/ship.md

@@ -6,6 +6,30 @@
 
 Opening question, calm tech lead voice: **has anyone actually *run* the rollback, or is it still a slide?** If only planned, that's today's work - say so plainly.
 
+## Deployment readiness gate (confirm the target before building the runway)
+
+Before scoring readiness, confirm WHERE this is going. State it in 2-3 lines - brief playback that invites correction:
+
+> "Deploying to: [target]. Pipeline: [how it gets there]. Rollback mechanism: [how to undo]. Any constraint I should know about?"
+
+**The checklist (confirm, don't assume):**
+
+| Dimension | Question | Status |
+|-----------|----------|--------|
+| **Target** | Cloud provider + service (ECS/Lambda/K8s/VM/on-prem)? | |
+| **Pipeline** | CI/CD exists? Manual? Who triggers prod deploy? | |
+| **Environments** | Dev → staging → prod path clear? Or deploying direct? | |
+| **Secrets** | Where do they live? (vault/SSM/env vars) Who provisions? | |
+| **Access** | Do YOU have deploy permissions, or does someone else push? | |
+| **Compliance** | Region constraints? Data residency? Encryption requirements? CAB/change window? | |
+| **Infra-as-code** | Terraform/Pulumi/CDK/manual? State file location? | |
+
+**If anything is blank:** ask now. Discovering deployment constraints AFTER build is where timelines slip. If the client hasn't defined these yet, that's a conversation before you write the runbook - not after.
+
+Write confirmed deployment context to `delivery.md` under a `## Deployment target` section.
+
+---
+
 ## Method - readiness gate (score before touching the deploy button)
 
 Score each dimension green/amber/red. This is the gate, not a suggestion: