diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 8d449f6..c6c60f1 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "fdeops", - "description": "Engagement memory for AI coding agents. One @fde skill routes the client work - land, discover, plan, build, ship, close - and the record of it (sponsor, promise, decision, acceptance, dated) lands in local .fde/ files as you confirm judgment. For Forward Deployed Engineers running several clients at once.", - "version": "3.12.0", + "description": "Engagement memory for AI coding agents. One @fde skill is the client record - brief wrong, they went quiet, when did we agree, what they got - and the dated memory (sponsor, promise, decision, acceptance) lands in local .fde/ files as you confirm judgment. For Forward Deployed Engineers running several clients at once.", + "version": "3.13.0", "category": "productivity", "tags": [ "community-managed" diff --git a/CHANGELOG.md b/CHANGELOG.md index 019d968..50a61e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,16 @@ # Changelog +## 3.13.0 — 2026-08-28 + +Four-day front: the skill is the engagement record, not a land-to-close operating system. + +### Changed +- **Four days first** — the brief is wrong, they went quiet, when did we agree, what did they get. `@fde` leads with those moments; the six-domain router stays behind them. +- **First chat binds** — name the client (`@fde this is Acme`); the agent runs `fde resume --init`. The FDE never types the CLI. Terminal `--init` remains the fallback. +- **Generic SDLC left the router** — `build`, `debug`, `observability`, `qa-live`, `security-audit`, and `test-on-legacy` live in `skills/fde/archive/sdlc/`. Routed count is 31 methods + 5 overlays. Coding, tests, and commits stay in the host agent. +- **Friday status leads with the value ledger** — promised → measured → accepted, then trust. A number nobody signed is claimed, not delivered. +- **README** teaches the job, then a 30-second install (plugin or `npx skills add --skill fde`). Method catalog is a details block. + ## 3.12.0 — 2026-08-27 Vocabulary: standard words on the outside, so nothing has to be learned before it works. diff --git a/README.md b/README.md index b7f83d9..ae99870 100644 --- a/README.md +++ b/README.md @@ -1,132 +1,128 @@ # FDEOps -**Your AI coding agent forgets your client every morning. FDEOps remembers.** +**The AI coding agent forgets the client. fdeops is the countersigned record — promised, measured, accepted.** [![npm version](https://img.shields.io/npm/v/fdeops.svg)](https://www.npmjs.com/package/fdeops) [![CI](https://github.com/suboss87/fdeops/actions/workflows/validate.yml/badge.svg)](https://github.com/suboss87/fdeops/actions) +[![skills.sh](https://skills.sh/b/suboss87/fdeops)](https://skills.sh/suboss87/fdeops) [![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) -**Engagement memory for AI coding agents.** Skill packs teach your agent how to *build*. None of them remember who the client is, what you promised, or who agreed it was delivered - close the window and it is gone. FDEOps adds that missing layer: a private record per client (`.fde/`), a field methodology from land to close, and one skill that routes it. +One `@fde` skill. Four days on an embed: -Built for Forward Deployed Engineers and anyone embedded in client work - consultants, agency developers, solutions architects, fractional CTOs. Not notes: a defensible record - dated, sourced, on your laptop. +**the brief is wrong · they went quiet · when did we agree · what did they get** -``` - land discover plan build ship close - | | | | | | - +-----------+-----------+---------+----------+---------+ - the fieldbook (.fde/) - one per engagement - written as a side effect of the work -``` +The host agent still writes the TypeScript, runs the tests, and makes the commits. This skill is the engagement record. Do not ask `@fde` to review a unit test. + +Talk in plain language. The AI coding agent runs the plumbing. You confirm anything that enters the record. --- -## A real session +## The week -Kickoff notes go in messy. You confirm what enters the record. A cold session the next morning already knows the client, the sponsor brief is grounded in dated facts, and the receipts survive the argument. Real CLI output - only the typing pace is staged, and you can [re-record it yourself](media/record-session.sh). +`@fde` plus English. No cheat sheet. -

A real fdeops session: messy kickoff notes routed into dated memory after you confirm, then a cold session that already knows the client, a grounded sponsor-meeting brief, and dated receipts

+| When | What you say | What you get | +|------|--------------|--------------| +| **The brief is wrong** | `@fde this is Acme. Brief says they want a portal.` | Real problem, or a gap. First chat: you name the client; the AI coding agent binds. | +| **They went quiet** | `@fde the sponsor went quiet` | Trust signal in the record — process gap vs trust problem. | +| **When did we agree?** | `@fde when did we agree to drop that?` | Dated receipts, or a clear gap. | +| **What did they get?** | `@fde what did they get this week` | Friday ledger: promised → measured → accepted. | +| **After a meeting** | `@fde` debrief these notes *(paste or attach)* | Proposed updates. You review, then confirm. | +| **Optional: pull** | `@fde` connect Granola *(once)* · `@fde` pull today's Acme transcript | You add that source MCP. We **pull** on request — no push, no sync. [mcp/recipes/](mcp/recipes/) | -Nothing to install to see it on a fake client: `npx fdeops demo`. +Same folder every time: `~/fde-engagements//.fde/`. + +**Words used here, once:** *engagement* - one client's body of work, one folder. *Fieldbook* - that folder (`.fde/`), the record itself. *Brief vs reality* - what they said the problem was, and what it turned out to be. *Terrain* - their systems and org as you actually found them. *Trust signal* - green / amber / red on one relationship. *Receipts* - the dated line proving something was agreed. *Vault* - the Obsidian copy `fde vault` generates to read it all in one window. --- ## Quickstart -**1. Install** on your machine - never in the customer's repo. +**1. Install** (30 seconds). Pick one — both copies `@fde` twice. + +Claude Code (hooks before you type): ```text /plugin marketplace add suboss87/fdeops /plugin install fdeops@fdeops ``` -```bash -npx skills add suboss87/fdeops --skill fde # Cursor, Codex, skills-compatible hosts -``` - -That is one skill, not a catalogue - `@fde` routes the whole method. The CLI needs no install either: the skill reaches for `npx fdeops` when `fde` is not on the PATH. (Drop `--skill fde` and you also get `testing-fieldbook`, which is for people contributing to this repo, not for field work.) - -Claude Code additionally gets session hooks, so context arrives before you type. Everywhere else it is the same fieldbook, loaded when you ask. - -**2. Bind once** in the client workspace: +Cursor, Codex, and any host that speaks the skills CLI: ```bash -npx fdeops resume --init garvey # ~/fde-engagements/garvey + bind this checkout -npx fdeops resume # where we are +npx skills add suboss87/fdeops --skill fde ``` -**3. Work** in plain language: +**2. One chat.** Name the client. The AI coding agent binds the engagement; you never type the CLI. ```text -New client, Garvey. Payments platform. They want it live before the Q3 audit. +@fde this is Acme ``` -No prefix needed - naming a client is enough. Say `@fde` when you want it explicitly. +Paste kickoff notes in the same thread. `@fde` routes; you confirm judgment. Workflow: [docs/USAGE.md](docs/USAGE.md). -**It is working if** `npx fdeops resume` prints this client's phase, trust signal, and next action - and prints the same thing tomorrow, from a new session, with no explaining. Full workflow: [docs/USAGE.md](docs/USAGE.md). +Claude Code auto-loads the fieldbook at session start. Elsewhere, say `@fde`. Tomorrow the file is still there.
-Other install paths · scan · env +Terminal bind · other hosts · env + +Fallback if the agent cannot bind — creates the engagement under `~/fde-engagements` and points this checkout at it: -- **Adapters:** `npx fdeops adapters .` - [adapters/](adapters/README.md) -- **Local LLMs:** load `skills/fde/SKILL.md` - [guide](adapters/LOCAL-LLM.md) +```bash +npx fdeops resume --init acme # ~/fde-engagements/acme + bind this checkout +npx fdeops resume # where we are +``` + +- **Adapters** (Cursor rules, Gemini, Copilot): `npx fdeops adapters .` — [adapters/](adapters/README.md) +- **Local LLMs:** load `skills/fde/SKILL.md` — [guide](adapters/LOCAL-LLM.md) - **Air-gapped:** `git clone https://github.com/suboss87/fdeops.git && cd fdeops && node bin/install.js` - **No install:** `npx fdeops demo` · `npx fdeops scan` (heuristic recon, not findings) - **Requires:** Node.js >= 18 -- **Override:** `FDEOPS_ENGAGEMENT` - [docs/install.md](docs/install.md) +- **Override:** `FDEOPS_ENGAGEMENT` — [docs/install.md](docs/install.md)
--- -## The week +## See it -**Say what happened, in your words.** There is nothing to memorise - no flags, no cheat sheet. The skill picks it up when you mention a client, debrief a meeting, or ask what was agreed; `@fde` is only the explicit way to summon it. +```bash +npx fdeops demo +``` -| When | What you say | What you get | -|------|--------------|--------------| -| **Start of week** | `@fde` - or just open Claude Code | Fieldbook on disk either way. **Claude Code** injects trust, phase, next before you type. **Cursor / Codex / others:** say `@fde` or `resume` - nothing auto-loads. | -| **After a meeting** | here are my notes from the Acme call *(paste or attach)* | Proposed updates. You review, then confirm. | -| **Optional: pull** | connect Granola *(once)* · pull today's Acme transcript | You add that source MCP. We **pull** on request - no push, no sync. [mcp/recipes/](mcp/recipes/) | -| **Before a stakeholder meeting** | prep me for tomorrow with the sponsor | Brief from what you already logged. | -| **Scope dispute** | when did we agree to drop that? | Dated answers, or a clear gap. | -| **End of week** | draft the sponsor update from the record | Status grounded in what happened. | +Real commands on a fake client: messy notes → you confirm → cold reload → prep → receipts → fieldbook page. Nothing of yours is read. Lives in `~/fde-engagements/.demo/`. Remove with `npx fdeops demo --clean`. -Same folder every time: `~/fde-engagements//.fde/`. +One recorded session — kickoff notes, next morning, “when did we agree?” weeks later. CLI output; typing pace is staged. Re-record: [`media/record-session.sh`](media/record-session.sh). ---- +

A real fdeops session: messy kickoff notes routed into dated memory after you confirm, then a cold session that already knows the client, a grounded sponsor-meeting brief, and dated receipts

-## How it works +Two things a chat window cannot do: **nothing is written until you confirm**, and `` lands sealed as `(private - redacted)` — never in `resume`, `prep`, `receipts`, or the dashboard. -- **You** describe the situation with `@fde`, in plain language. -- **The AI coding agent** routes to a method, does the work, and drafts the memory. -- **The CLI** (`bin/fde.js`) does every write, receipt, and status check - git and file reads only, no network, no model tokens. You do not live in the CLI; your agent runs it. [docs/USAGE.md](docs/USAGE.md) -- **You confirm.** Nothing enters the record unreviewed; `fde debrief --dry-run` shows the routing first. +--- -`CLAUDE.md` is how the *code* works. The fieldbook is how the *engagement* works. It lives at `~/fde-engagements//.fde/`, not inside any vendor - change hosts, install `@fde` on the new one, keep talking. +## How it works -### What works where +- **You** describe the situation with `@fde` (or plain language once the skill is loaded). First chat: you name the client; the AI coding agent runs the bind. +- **Hooks (Claude Code)** load where you left off and snapshot on the way out. Other hosts: same CLI and files; you call `@fde`. +- **Local CLI** — writes, receipts, status. Zero model tokens. The AI coding agent runs it; you do not live in the CLI. Friday, `fde status` prints promised → measured → accepted. [docs/USAGE.md](docs/USAGE.md) +- **Pull (optional)** — FDEOps is the sink. Paste is the daily path. A source MCP you add (Granola, Slack, Notion, …) can fetch text; `@fde connect …` walks config. No push, no sync, no tokens in `.fde/`. [mcp/recipes/](mcp/recipes/) -Honest boundaries, so nothing here needs a footnote: +`CLAUDE.md` is how the *code* works. The fieldbook is how the *engagement* works. The record lives at `~/fde-engagements//.fde/` — not inside any vendor. -| | Claude Code | Cursor · Codex · Copilot · Gemini · local LLMs | -|---|---|---| -| Fieldbook, methods, CLI, dashboard | yes | yes | -| Context loaded before you type | session hooks | you say `@fde` / `resume` | -| Snapshot on session end | session hooks | `@fde` capture, or `fde capture` | -| Pull from Granola / Slack / Notion | you add that source MCP; FDEOps only ingests | same | +### Switch coding agents anytime -FDEOps is the sink, never the source: no push, no sync, no third-party tokens in `.fde/`. [mcp/recipes/](mcp/recipes/) +Change hosts, install `@fde` on the new one, bind if needed, keep talking. The client record does not move.
-Phase verbs (land → close) +Engagement verbs | Verb | When | |------|------| -| **land** | First days - brief, stakeholders, success | -| **discover** | The brief is wrong - evidence from the repo | +| **land** | First days — brief, stakeholders, success | +| **discover** | The brief is wrong — evidence from the repo | | **plan** | Sequence backwards from done, PR-sized | -| **build** | Blast radius, log what shipped | +| log delivery | After the host agent codes — what shipped, how it rolls back | | **ship** | Pre-flight, canary, rollback | | **close** | Handoff, retro, receipts that survive you | @@ -138,50 +134,26 @@ Overlays (AI, fintech, healthcare, gov) fire on signal. [docs/skills.md](docs/sk ## Engagement memory (`.fde/`) -One folder per client. Plain markdown, so you can grep it, diff it, copy it into a readout, and defend it in a room. +One folder per client. Plain markdown. Grep it, copy it, defend it. | File | Holds | |------|-------| | `context.md` | Where you are | -| `brief.md` / `success.md` | What they asked; what "done" is and who signs | +| `brief.md` / `success.md` | What they asked; what “done” is and who signs | | `reality.md` / `terrain.md` | The real problem; the map | | `stakeholders.md` | `[signal:green\|amber\|red]` | | `trust-profile.md` | Sacred data, AI policy, approval chain | | `decisions.md` / `risks.md` / `delivery.md` | Dated choices; live risks; what shipped and how it rolls back | -A day-one fieldbook ships **empty** - headings and allowed values, no invented rows - so anything you read in it is something that actually happened. Schema: [docs/schema.md](docs/schema.md). - -**Words used here, once:** *engagement* - one client's body of work, one folder. *Fieldbook* - that folder (`.fde/`), the record itself. *Brief vs reality* - what they said the problem was, and what it turned out to be. *Terrain* - their systems and org as you actually found them. *Trust signal* - green / amber / red on one relationship. *Receipts* - the dated line proving something was agreed. *Vault* - the Obsidian copy `fde vault` generates to read it all in one window. - ---- - -## The field methods - -You never pick one. You describe the situation and `@fde` routes. **37 methods** across six domains, each a method - thinking, artifact, checkpoint - not a tip sheet. [docs/skills.md](docs/skills.md) · [docs/skills-reference.md](docs/skills-reference.md) - -
-All 37 methods - -| Domain | Methods | -|--------|---------| -| **1. Embed & Trust** | [land](skills/fde/references/land.md) · [audit](skills/fde/references/audit.md) · [stakeholder-radar](skills/fde/references/stakeholder-radar.md) · [trust-engineering](skills/fde/references/trust-engineering.md) · [scope-defense](skills/fde/references/scope-defense.md) | -| **2. Discover & Diagnose** | [discover](skills/fde/references/discover.md) · [assumption-audit](skills/fde/references/assumption-audit.md) · [use-case-scoring](skills/fde/references/use-case-scoring.md) · [sketch](skills/fde/references/sketch.md) | -| **3. Plan & Align** | [plan](skills/fde/references/plan.md) · [business-case](skills/fde/references/business-case.md) · [options-analysis](skills/fde/references/options-analysis.md) · [initiative-triage](skills/fde/references/initiative-triage.md) | -| **4. Build & Guard** | [build](skills/fde/references/build.md) · [incremental-build](skills/fde/references/incremental-build.md) · [test-on-legacy](skills/fde/references/test-on-legacy.md) · [blast-radius](skills/fde/references/blast-radius.md) · [debug](skills/fde/references/debug.md) · [rescue](skills/fde/references/rescue.md) · [security-audit](skills/fde/references/security-audit.md) · [observability](skills/fde/references/observability.md) | -| **5. Ship & Verify** | [ship](skills/fde/references/ship.md) · [review](skills/fde/references/review.md) · [rollback-drill](skills/fde/references/rollback-drill.md) · [qa-live](skills/fde/references/qa-live.md) | -| **6. Operate & Close** | [status](skills/fde/references/status.md) · [demo-prep](skills/fde/references/demo-prep.md) · [debrief](skills/fde/references/debrief.md) · [exec-narrative](skills/fde/references/exec-narrative.md) · [dashboard](skills/fde/references/dashboard.md) · [multi-customer-ops](skills/fde/references/multi-customer-ops.md) · [close](skills/fde/references/close.md) · [handoff-engineering](skills/fde/references/handoff-engineering.md) · [pattern-extract](skills/fde/references/pattern-extract.md) · [red-team](skills/fde/references/red-team.md) · [ingest](skills/fde/references/ingest.md) · [ingest-connect](skills/fde/references/ingest-connect.md) | - -Overlays: [ai](skills/fde/references/ai.md) · [artifacts](skills/fde/references/artifacts.md) · [fintech](skills/fde/references/fintech.md) · [healthcare](skills/fde/references/healthcare.md) · [gov](skills/fde/references/gov.md) - -
+Schema: [docs/schema.md](docs/schema.md). --- ## Fieldbook UI -`@fde` dashboard, or `npx fdeops dashboard` (`--all` for the portfolio): one local HTML file - trust, phase, next action, and the record behind them. Generated on demand, no server. +Local HTML: trust, phase, next, the record. `@fde` dashboard, or `npx fdeops dashboard` (`--all` for the portfolio). -

The fdeops Fieldbook dashboard: engagements with trust signal, phase and next action

+

fdeops Fieldbook in the browser

--- @@ -189,32 +161,35 @@ Overlays: [ai](skills/fde/references/ai.md) · [artifacts](skills/fde/references | You are | What this is | |---------|----------------| -| **Forward Deployed Engineer** | The job this was built for - first meeting through handoff | +| **Forward Deployed Engineer** | The job this was built for — first meeting through handoff | | **Consultant / contractor on site** | The engagement stops resetting every morning | | **Solutions architect** | Politics and architecture in the same record | -| **Agency, 3-5 clients** | One `.fde/` each - they stop blurring | +| **Agency, 3–5 clients** | One `.fde/` each — they stop blurring | | **Fractional CTO on client work** | System of record for the embed, and the billable trail | +Ordinary TypeScript, unit tests, and git commits stay in the host agent. + --- ## Your data stays yours - **Local only.** `git` + files. No network, no telemetry, no account. Air-gapped is fine. -- **Plain markdown.** No database, no lock-in, nothing to export. -- **No new data path.** The model sees client code only when you point the AI coding agent at it. `` blocks are redacted from CLI, dashboard, and hook output - do not open raw private blocks with file tools. -- **Know the sync surface.** `~/fde-engagements` lives in `$HOME`. iCloud or Dropbox is an NDA incident waiting; `resume --init` warns you. +- **Plain markdown.** No database. +- **No new data path.** The model sees client code only when you point the AI coding agent at it. `` is redacted from CLI, dashboard, and hooks — do not open raw private blocks with file tools. +- **Nothing unreviewed.** Draft → you confirm. `fde debrief --dry-run` shows routing first. +- **Know the sync surface.** `~/fde-engagements` is in `$HOME`. iCloud/Dropbox is an NDA incident waiting. `resume --init` warns. [PRIVACY.md](PRIVACY.md) before the first NDA. -[PRIVACY.md](PRIVACY.md) before the first NDA · [SECURITY.md](SECURITY.md) +[PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md) --- ## Principles -- **The artifact is the memory** - producing the work and recording it are one action -- **Methods, not autonomy** - the kit says what to check; judgment stays yours -- **Brief is a hypothesis** - discover before building the wrong thing -- **Evidence on every claim** - these files get defended in the room -- **One customer, one folder** - context never bleeds +- **The artifact is the memory** — producing the work and recording it are one action +- **Methods, not autonomy** — the kit says what to check; judgment stays yours +- **Brief is a hypothesis** — discover before building the wrong thing +- **Evidence on every claim** — these files get defended in the room +- **One customer, one folder** — context never bleeds --- @@ -228,8 +203,26 @@ Re-run the Quickstart install, or from a clone: `git pull && node bin/install.js **[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. [Issues](https://github.com/suboss87/fdeops/issues) · [CONTRIBUTING.md](CONTRIBUTING.md) -Thanks to builders whose craft sharpened the thinking, among them [Andrej Karpathy](https://karpathy.ai/)'s engineering guidelines and the [agentic engineering workflow](https://github.com/pawel-cell/micky-podcast-agentic-engineering) notes from David Ondrej / Michael Shimeles. - -**What we won't build:** SaaS sync; Slack/Notion/Granola connectors or **push** inside the CLI; CRM as core; hardware capture; generic code-craft packs (TDD and review live elsewhere). You may **pull** via *your* MCP. The `fde` CLI stays local-only. +**What we won't build:** SaaS sync; Slack/Notion/Granola connectors or **push** inside the CLI; CRM as core; hardware capture; generic code-craft packs. You may **pull** via *your* MCP. The `fde` CLI stays local-only. [FDE Methodology](FDE-METHODOLOGY.md) · [SECURITY.md](SECURITY.md) · [PRIVACY.md](PRIVACY.md) · [Repo layout](docs/REPO_LAYOUT.md) · [Skills matrix](docs/skills.md) · MIT + +--- + +
+31 field methods (you never pick one) + +You describe the situation; `@fde` routes. **31 methods**, six domains — each a method (thinking, artifact, checkpoint), not a tip sheet. [docs/skills.md](docs/skills.md) · [docs/skills-reference.md](docs/skills-reference.md) + +| Domain | Methods | +|--------|---------| +| **1. Embed & Trust** | [land](skills/fde/references/land.md) · [audit](skills/fde/references/audit.md) · [stakeholder-radar](skills/fde/references/stakeholder-radar.md) · [trust-engineering](skills/fde/references/trust-engineering.md) · [scope-defense](skills/fde/references/scope-defense.md) | +| **2. Discover & Diagnose** | [discover](skills/fde/references/discover.md) · [assumption-audit](skills/fde/references/assumption-audit.md) · [use-case-scoring](skills/fde/references/use-case-scoring.md) · [sketch](skills/fde/references/sketch.md) | +| **3. Plan & Align** | [plan](skills/fde/references/plan.md) · [business-case](skills/fde/references/business-case.md) · [options-analysis](skills/fde/references/options-analysis.md) · [initiative-triage](skills/fde/references/initiative-triage.md) | +| **4. Build & Guard** | [incremental-build](skills/fde/references/incremental-build.md) · [blast-radius](skills/fde/references/blast-radius.md) · [rescue](skills/fde/references/rescue.md) | +| **5. Ship & Verify** | [ship](skills/fde/references/ship.md) · [review](skills/fde/references/review.md) · [rollback-drill](skills/fde/references/rollback-drill.md) | +| **6. Operate & Close** | [status](skills/fde/references/status.md) · [demo-prep](skills/fde/references/demo-prep.md) · [debrief](skills/fde/references/debrief.md) · [exec-narrative](skills/fde/references/exec-narrative.md) · [dashboard](skills/fde/references/dashboard.md) · [multi-customer-ops](skills/fde/references/multi-customer-ops.md) · [close](skills/fde/references/close.md) · [handoff-engineering](skills/fde/references/handoff-engineering.md) · [pattern-extract](skills/fde/references/pattern-extract.md) · [red-team](skills/fde/references/red-team.md) · [ingest](skills/fde/references/ingest.md) · [ingest-connect](skills/fde/references/ingest-connect.md) | + +Overlays: [ai](skills/fde/references/ai.md) · [artifacts](skills/fde/references/artifacts.md) · [fintech](skills/fde/references/fintech.md) · [healthcare](skills/fde/references/healthcare.md) · [gov](skills/fde/references/gov.md) + +
diff --git a/adapters/AGENTS.md b/adapters/AGENTS.md index 01a48ca..813414b 100644 --- a/adapters/AGENTS.md +++ b/adapters/AGENTS.md @@ -4,10 +4,13 @@ You are the AI coding agent for a **Forward Deployed Engineer (FDE)** - the huma ## Entry -When the FDE types **`@fde`** (or describes an engagement situation - new customer, mid-project takeover, production fire, quiet stakeholder, ready to ship), load the skill and route. +When the FDE types **`@fde`**, names a client, pastes meeting notes, asks what was agreed, or describes embed work (quiet sponsor, brief feels wrong, Friday update) — load the skill. If `fde resume` says NO ENGAGEMENT: ask the client name once, then **you** run `fde resume --init `. Never tell them to type it. + +Do **not** load `@fde` for ordinary code edits, TypeScript, unit tests, refactors, or git commits. - Skill (single source of truth): `~/.claude/skills/fde/SKILL.md` - **Never ask the FDE to pick a skill.** Read the situation, route silently, do the work. +- **Never ask the FDE to type `fde …` commands.** You run the local CLI; they confirm judgment in chat. ## Engagement memory diff --git a/adapters/GEMINI.md b/adapters/GEMINI.md index 804c575..e4abfae 100644 --- a/adapters/GEMINI.md +++ b/adapters/GEMINI.md @@ -4,10 +4,13 @@ Context for Gemini CLI when assisting a **Forward Deployed Engineer (FDE)** - th ## Entry -When the FDE types **`@fde`** or describes an engagement situation (new customer, mid-project takeover, production fire, quiet stakeholder, ready to ship), load the skill and route. +When the FDE types **`@fde`**, names a client, pastes meeting notes, asks what was agreed, or describes embed work (quiet sponsor, brief feels wrong, Friday update) — load the skill. If `fde resume` says NO ENGAGEMENT: ask the client name once, then **you** run `fde resume --init `. Never tell them to type it. + +Do **not** load `@fde` for ordinary code edits, TypeScript, unit tests, refactors, or git commits. - Skill (single source of truth): `~/.claude/skills/fde/SKILL.md` - **Never ask the FDE to pick a skill.** Read the situation, route silently, do the work. +- **Never ask the FDE to type `fde …` commands.** You run the local CLI; they confirm judgment in chat. ## Engagement memory diff --git a/adapters/LOCAL-LLM.md b/adapters/LOCAL-LLM.md index 7e800dd..2803c42 100644 --- a/adapters/LOCAL-LLM.md +++ b/adapters/LOCAL-LLM.md @@ -62,7 +62,7 @@ The model reads SKILL.md, routes to the right skill, and produces artifacts in y ## Model size recommendations -The methodology is detailed (37 methods, routing logic, evidence format, memory contract). Larger models handle it better: +The methodology is detailed (31 methods, routing logic, evidence format, memory contract). Larger models handle it better: | Model class | Experience | |-------------|-----------| diff --git a/adapters/README.md b/adapters/README.md index f6f1c40..17a87d2 100644 --- a/adapters/README.md +++ b/adapters/README.md @@ -2,7 +2,7 @@ **One brain, thin adapters.** fdeops has a single source of truth - the `@fde` skill at `skills/fde/SKILL.md` and the `fde` CLI. Each AI coding tool discovers it through a small pointer file in the place that tool already looks. No forked logic, no five copies to maintain - every adapter says the same thing: *route via `@fde`, read/write `.fde/` memory, talk like a peer, never touch what isn't yours.* -**Switching tools:** the fieldbook does not live in the agent. It lives at `~/fde-engagements//.fde/`. Point a new tool at a bound workspace, drop adapters (or install the skill/plugin for that tool), and the same client record opens. Auto session hooks are Claude Code–first; elsewhere load via `@fde` / `fde resume`. See [README § What works where](../README.md#what-works-where). +**Switching tools:** the fieldbook does not live in the agent. It lives at `~/fde-engagements//.fde/`. Point a new tool at a bound workspace, drop adapters (or install the skill/plugin for that tool), and the same client record opens. Auto session hooks are Claude Code–first; elsewhere load via `@fde` / `fde resume`. See [README § Switch coding agents](../README.md#switch-coding-agents-anytime). ## What goes where @@ -31,4 +31,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 37 methods, 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 31 methods, 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. diff --git a/adapters/copilot-instructions.md b/adapters/copilot-instructions.md index f362d47..9c2c4c0 100644 --- a/adapters/copilot-instructions.md +++ b/adapters/copilot-instructions.md @@ -4,10 +4,13 @@ You are the AI coding agent for a **Forward Deployed Engineer (FDE)** - the huma ## Entry -When the FDE types **`@fde`** or describes an engagement situation (new customer, mid-project takeover, production fire, quiet stakeholder, ready to ship), load the skill and route. +When the FDE types **`@fde`**, names a client, pastes meeting notes, asks what was agreed, or describes embed work (quiet sponsor, brief feels wrong, Friday update) — load the skill. If `fde resume` says NO ENGAGEMENT: ask the client name once, then **you** run `fde resume --init `. Never tell them to type it. + +Do **not** load `@fde` for ordinary code edits, TypeScript, unit tests, refactors, or git commits. - Skill (single source of truth): `~/.claude/skills/fde/SKILL.md` - **Never ask the FDE to pick a skill.** Read the situation, route silently, do the work. +- **Never ask the FDE to type `fde …` commands.** You run the local CLI; they confirm judgment in chat. ## Engagement memory diff --git a/adapters/cursor.fde.mdc b/adapters/cursor.fde.mdc index 940d1d5..e91505e 100644 --- a/adapters/cursor.fde.mdc +++ b/adapters/cursor.fde.mdc @@ -9,9 +9,11 @@ You are the AI coding agent for a **Forward Deployed Engineer (FDE)** - the huma ## Entry -When the FDE types **`@fde`** or describes an engagement situation in plain language (new customer, meeting notes, prep for a stakeholder meeting, scope dispute, ready to ship), load the skill and route. +When the FDE types **`@fde`**, names a client, pastes meeting notes, asks what was agreed, or describes embed work (quiet sponsor, brief feels wrong, Friday update) — load `@fde`. If `fde resume` says NO ENGAGEMENT: ask the client name once, then **you** run `fde resume --init `. Never tell them to type it. -- Skill (single source of truth): `~/.claude/skills/fde/SKILL.md` +Do **not** load `@fde` for ordinary code edits, unit tests, refactors, or git commits. + +- Skill (single source of truth): `~/.claude/skills/fde/SKILL.md` (or the copy this install placed) - **Never ask the FDE to pick a skill.** Read the situation, route silently, do the work. - **Never ask the FDE to type `fde …` commands.** You run the local CLI; they confirm judgment in chat. diff --git a/bin/check.js b/bin/check.js index 402c364..39aeba3 100644 --- a/bin/check.js +++ b/bin/check.js @@ -59,8 +59,8 @@ ok('skills structure') // v3: one skill + phase references (progressive disclosure) const requiredReferences = [ - 'land.md', 'discover.md', 'audit.md', 'plan.md', 'build.md', 'review.md', - 'debug.md', 'rescue.md', 'ship.md', 'sketch.md', 'close.md', 'dashboard.md', + 'land.md', 'discover.md', 'audit.md', 'plan.md', 'review.md', + 'rescue.md', 'ship.md', 'sketch.md', 'close.md', 'dashboard.md', 'debrief.md', 'status.md', 'demo-prep.md', 'healthcare.md', 'fintech.md', 'gov.md', 'ai.md', 'eval-pack.md', @@ -80,7 +80,7 @@ ok('phase references') // every judgment-heavy reference carries a worked example that names the memory // file the work lands in. Prose-only guidance drifts into advice nobody can apply. const exampleReferences = [ - 'land.md', 'discover.md', 'plan.md', 'build.md', 'ship.md', 'close.md', + 'land.md', 'discover.md', 'plan.md', 'ship.md', 'close.md', 'status.md', 'stakeholder-radar.md', 'options-analysis.md', 'business-case.md', 'assumption-audit.md', 'scope-defense.md', ] diff --git a/bin/fde.js b/bin/fde.js index b85f61e..b75f409 100755 --- a/bin/fde.js +++ b/bin/fde.js @@ -24,7 +24,7 @@ * fde receipts "what did we agree?" - search memory with dates * fde capture session-end snapshot → context.md (hooks use this) * fde preserve pre-compaction context snapshot (hook-internal; hooks use this) - * fde status [--all] current engagement (default) or full portfolio (--all) + * fde status [--all] value ledger first, then trust (pass --all for portfolio) * fde dashboard [--all] current engagement fieldbook (default) or all (--all) * fde vault derived Obsidian vault of the fieldbook (disposable; --redacted) */ @@ -1223,7 +1223,7 @@ function cmdResume(args) { .filter(d => !d.startsWith('.') && fs.existsSync(path.join(ENGAGEMENTS_ROOT, d, '.fde'))) .join(', ') || '(none yet)' : '(none yet)' - console.log(`NO ENGAGEMENT for this workspace.\nexisting: ${list}\ncreate + bind one: fde resume --init `) + console.log(`NO ENGAGEMENT for this workspace.\nexisting: ${list}\nAsk the human the client name (one question), then run: fde resume --init \nDo not tell them to type that command.`) process.exit(2) } // Monday-morning: triage + proactive hygiene (silent when clean), then memory. @@ -2295,21 +2295,59 @@ function hasValueBucket(eng) { const PENDING_CELL_RE = /^(?:pending|tbd|to ?be ?(?:measured|confirmed|determined)|n\s*\/\s*a|na|none|unknown|not measured|\?+|\.{2,}|…|-+|—+|–+)(?:[^\w].*)?$/i -function claimedValueRows(eng) { +function parseValueLedger(eng) { const ledger = stripTemplateNoise(sectionBody(readClean(eng, 'delivery.md'), 'Value ledger') || '') const table = parseMdTable(ledger) - if (!table) return { claimed: 0, columnMissing: false } - const mIdx = colIndex(table.headers, /measured/i) - if (mIdx === -1) return { claimed: 0, columnMissing: false } - const aIdx = colIndex(table.headers, /accept/i) - let claimed = 0 + if (!table) return { rows: [], columnMissing: false } + const idx = { + slice: colIndex(table.headers, /slice/i), + promised: colIndex(table.headers, /promised/i), + measured: colIndex(table.headers, /measured/i), + accepted: colIndex(table.headers, /accept/i), + } + const cell = (row, i) => (i === -1 ? '' : String(row[i] || '').trim()) + const rows = [] for (const row of table.rows) { - const measured = String(row[mIdx] || '').trim() - if (!measured || PENDING_CELL_RE.test(measured)) continue - const accepted = aIdx === -1 ? '' : String(row[aIdx] || '').trim() - if (!accepted || PENDING_CELL_RE.test(accepted)) claimed++ + const slice = cell(row, idx.slice) + const promised = cell(row, idx.promised) + const measured = cell(row, idx.measured) + const accepted = cell(row, idx.accepted) + if (!slice && !promised && !measured) continue + const measuredPending = !measured || PENDING_CELL_RE.test(measured) + const acceptedPending = idx.accepted === -1 || !accepted || PENDING_CELL_RE.test(accepted) + let state = 'unmeasured' + if (!measuredPending && acceptedPending) state = 'claimed' + else if (!measuredPending) state = 'accepted' + rows.push({ slice, promised, measured, accepted, state }) } - return { claimed, columnMissing: aIdx === -1 } + return { rows, columnMissing: idx.accepted === -1 } +} + +function claimedValueRows(eng) { + const { rows, columnMissing } = parseValueLedger(eng) + return { claimed: rows.filter(r => r.state === 'claimed').length, columnMissing } +} + +function formatValueLedgerLine(r) { + const name = r.slice || 'value' + let body = r.promised || '' + if (r.state !== 'unmeasured' && r.measured) { + if (!body) body = r.measured + else if (!body.includes(r.measured)) body = `${body} → ${r.measured}` + } + const head = body ? `${name}: ${body}` : name + if (r.state === 'accepted') return `${head} · accepted by ${r.accepted}` + if (r.state === 'claimed') return `${head} · claimed, not yet accepted` + return `${head} · not yet measured` +} + +function valueLedgerStatusLines(eng, opts = {}) { + const { rows } = parseValueLedger(eng) + if (!rows.length) return [' value: none yet'] + const cap = opts.compact ? 1 : 8 + const lines = rows.slice(0, cap).map(r => ` ${formatValueLedgerLine(r)}`) + if (rows.length > cap) lines.push(` … ${rows.length - cap} more in delivery.md`) + return lines } // AI in scope for ship/close hygiene — delivery/decisions/trust evidence only. @@ -2669,7 +2707,7 @@ function cmdStatus(args) { if (!fs.existsSync(eng)) continue const s = computeSignals(eng) const note = [s.memoryWarn, (s.dirtyFiles && s.dirtyFiles.length) ? `dirty:${s.dirtyFiles.length}` : '', s.reason || s.topRisk].filter(Boolean).join(' · ').slice(0, 70) - rows.push({ name: d, phase: s.phase, trust: s.trust, signalAge: s.signalAge, stale: s.stale, updated: s.updated, reason: note, memoryWarn: s.memoryWarn, dirtyFiles: s.dirtyFiles }) + rows.push({ name: d, phase: s.phase, trust: s.trust, signalAge: s.signalAge, stale: s.stale, updated: s.updated, reason: note, memoryWarn: s.memoryWarn, dirtyFiles: s.dirtyFiles, valueLines: valueLedgerStatusLines(eng, { compact: true }) }) } } else { const eng = resolveEngagement() @@ -2679,13 +2717,14 @@ function cmdStatus(args) { } const s = computeSignals(eng) const note = [s.memoryWarn, (s.dirtyFiles && s.dirtyFiles.length) ? `dirty:${s.dirtyFiles.length}` : '', s.reason || s.topRisk].filter(Boolean).join(' · ').slice(0, 70) - rows.push({ name: engagementSlugFromPath(eng), phase: s.phase, trust: s.trust, signalAge: s.signalAge, stale: s.stale, updated: s.updated, reason: note, memoryWarn: s.memoryWarn, dirtyFiles: s.dirtyFiles }) + rows.push({ name: engagementSlugFromPath(eng), phase: s.phase, trust: s.trust, signalAge: s.signalAge, stale: s.stale, updated: s.updated, reason: note, memoryWarn: s.memoryWarn, dirtyFiles: s.dirtyFiles, valueLines: valueLedgerStatusLines(eng) }) } if (!rows.length) { console.log('no engagements yet'); return } const order = { RED: 0, amber: 1, green: 2 } rows.sort((a, b) => order[a.trust] - order[b.trust]) - console.log((all ? 'FDE PORTFOLIO' : 'FDE STATUS') + ' - trust-first triage (heuristic: red > amber > green)\n') + console.log((all ? 'FDE PORTFOLIO' : 'FDE STATUS') + ' - value first, then trust\n') for (const r of rows) { + for (const line of r.valueLines) console.log(line) // "amber?" = structured signal went stale (>21d) - reconfirm before trusting it const label = r.trust + (r.stale ? '?' : '') const sig = r.signalAge != null ? `signal ${r.signalAge}d old${r.stale ? ' (STALE - reconfirm)' : ''} ` : '' @@ -3153,7 +3192,7 @@ function printUsage() { fde tidy [--apply] propose safe consolidations (contract: no new facts; git-reversible) fde owner [set email] who keeps this engagement record fde receipts "what did we agree?" with dates - fde status [--all] current engagement status (pass --all for full portfolio) + fde status [--all] value ledger, then trust (pass --all for full portfolio) fde dashboard [--all] current engagement fieldbook (pass --all for every client) fde vault derived Obsidian vault of every engagement (--current for one, --redacted for a shared screen, --out ) hooks call these; you do not: capture (session-end snapshot), preserve (pre-compaction snapshot) diff --git a/docs/REPO_LAYOUT.md b/docs/REPO_LAYOUT.md index 84038b1..bde1d2c 100644 --- a/docs/REPO_LAYOUT.md +++ b/docs/REPO_LAYOUT.md @@ -2,7 +2,8 @@ | Path | Purpose | |------|---------| -| `skills/fde/` | **The one skill** - router (`SKILL.md`) + 37 methods, 5 overlays, and AI companion `eval-pack` under `references/` - installed to `~/.claude/skills/` | +| `skills/fde/` | **The one skill** - router (`SKILL.md`) + 31 routed methods, 5 overlays, and AI companion `eval-pack` under `references/` - installed to `~/.claude/skills/` | +| `skills/fde/archive/sdlc/` | Archived SDLC methods (`build`, `debug`, `observability`, `qa-live`, `security-audit`, `test-on-legacy`) - kept for history, **not routed** | | `adapters/` | Thin per-tool pointers (Codex/`AGENTS.md`, Gemini, Cursor, Copilot, local LLMs) - `node bin/install.js adapters ` | | `templates/.fde/` | Core memory templates for `fde resume --init` (phase artifacts are created by phases on demand; `evals.md` is optional) | | `examples/` | Fictional walkthroughs with sample `.fde/` files | diff --git a/docs/USAGE.md b/docs/USAGE.md index b816f34..9055e0c 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -4,29 +4,19 @@ **Terminology:** [README § Who this is for](../README.md#who-this-is-for) - **"agent" = AI software, not a human.** -**Start here:** [README](../README.md) (30-second proof → engagement layer → Quickstart). +**Start here:** [README](../README.md) (four days → 30-second install → one chat). Day-to-day reference below. --- -## See one session end to end - -Kickoff notes → you confirm → cold reload → sponsor prep → dated receipts → fieldbook. Real CLI output; only the typing pace is staged. Re-record it yourself with [`media/record-session.sh`](../media/record-session.sh). - -

A real fdeops session: messy kickoff notes routed into dated memory after you confirm, then a cold session that already knows the client, a grounded sponsor-meeting brief, and dated receipts

- -`` lands sealed as `(private - redacted)` - never in `resume`, `prep`, `receipts`, or the dashboard. - ---- - ## New here? (5 minutes) -1. Run `npx fdeops scan` in a repo - recon + the "ASK ON DAY 1" questions, zero config -2. Read **Who this is for** and **Without fdeops vs with fdeops** in the README -3. Bind a workspace: `fde resume --init ` (the one setup step) -4. Skim [examples/garvey-payments/](../examples/garvey-payments/) Day 1 → Day 10 -5. In your **AI chat** (not email to a person): `@fde` + your actual situation +1. Install from the README (plugin or `npx skills add`), then in chat: `@fde this is Acme` — the AI coding agent binds. Terminal fallback: `fde resume --init ` +2. Read **The week** and **Who this is for** in the README +3. Skim [examples/garvey-payments/](../examples/garvey-payments/) Day 1 → Day 10 +4. Optional recon, zero config: `npx fdeops scan` in a repo +5. Then: `@fde` + the actual situation (brief wrong, they went quiet, when did we agree, what they got) You do not read the phase methods. **`@fde` routes the AI and loads the right one.** @@ -36,7 +26,7 @@ You do not read the phase methods. **`@fde` routes the AI and loads the right on | You are… | Example message to the **AI coding agent** | |----------|---------------------------------------------| -| Starting | `@fde New embed. First meeting tomorrow. Brief says: …` | +| Starting | `@fde this is Acme` (binds) then `@fde New embed. First meeting tomorrow. Brief says: …` | | Unsure of real problem | `@fde Workshop done. Ops says they use a spreadsheet nightly.` | | Just out of a meeting | `@fde Debrief: ` | | Ready to code | `@fde Ship smallest slice by Friday in module X.` | @@ -105,10 +95,10 @@ That writes a `[signal:amber]` token into `stakeholders.md`. The **latest dated **You do not need these for daily work.** Chat with `@fde`; the agent runs them. Use the terminal for one-time setup, air-gapped machines, or automation. -**Humans - once / occasional:** +**Humans - once / occasional** (prefer chat: `@fde this is Acme`): ```bash -npx fdeops resume --init # one-time: create + bind this workspace +npx fdeops resume --init # fallback: create + bind this workspace from the terminal npx fdeops resume # check "where we are" npx fdeops scan # try day-1 recon with no install npx fdeops dashboard # optional local HTML view of the fieldbook @@ -143,8 +133,9 @@ fde log decision "…" fde log contact "…" --signal amber fde receipts "descope" # dated agreements (ON RECORD) fde dashboard --all # every client, sorted by trust -fde status [--all] # trust-first triage +fde status [--all] # value ledger, then trust fde vault [--redacted] [--out D] # derived Obsidian vault of the whole portfolio (disposable) +fde tidy [--apply] # propose safe consolidations (fde garden still works) fde demo # the whole loop on a fake client (--clean removes it) ``` @@ -178,7 +169,7 @@ cd ~/work/client-a && fde resume --init client-a cd ~/work/client-b && fde resume --init client-b ``` -One folder per client, one binding per workspace. Never merge contexts. `fde status` triages the whole portfolio (red > amber > green); `fde dashboard` renders it into one offline HTML fieldbook. +One folder per client, one binding per workspace. Never merge contexts. `fde status` prints the value ledger (promised → measured → accepted), then trust; `fde dashboard` renders it into one offline HTML fieldbook. --- diff --git a/docs/skills-reference.md b/docs/skills-reference.md index b5d8cee..35abace 100644 --- a/docs/skills-reference.md +++ b/docs/skills-reference.md @@ -1,4 +1,4 @@ -# fdeops Reference - one skill, 37 methods across 6 domains +# fdeops Reference - one skill, 31 methods across 6 domains v3 ships **one skill**: `@fde` ([skills/fde/SKILL.md](../skills/fde/SKILL.md)). You describe the situation; it routes to a phase and follows that phase's method from [skills/fde/references/](../skills/fde/references/). Engagement memory lives in `~/fde-engagements//.fde/` (one folder per customer). @@ -44,14 +44,9 @@ Each reference is a **method, not advice**: the thinking the agent does, the art | Skill | What it does | Use when | |-------|-------------|----------| -| [build](../skills/fde/references/build.md) | Blast radius + legacy safety + **integration design** + **team amplification** | Ready to build, implementing, legacy change, ship a feature end to end | | [incremental-build](../skills/fde/references/incremental-build.md) | Vertical slices, 100-300 lines each, visible progress every 2-3 days | Large feature, need visible progress every 2-3 days | -| [test-on-legacy](../skills/fde/references/test-on-legacy.md) | Characterise first, Strangler Fig, spot lying tests | No tests, legacy code, need to make changes safely | | [blast-radius](../skills/fde/references/blast-radius.md) | Trace dependencies, classify impact (CONTAINED -> IRREVERSIBLE) | What could go wrong, touching shared infrastructure, need to assess impact | -| [debug](../skills/fde/references/debug.md) | Systematic: reproduce -> isolate -> one hypothesis -> verify | Something's broken, can't reproduce, shouldn't be happening | | [rescue](../skills/fde/references/rescue.md) | Production fire, trust fire, wrong-brief-mid-build, **or full pivot** | Production down, urgent - or stakeholder gone quiet, trust slipping | -| [security-audit](../skills/fde/references/security-audit.md) | Threat model in 5 minutes, STRIDE pass, secrets scan | Security check, auth/payments/user data, compliance question | -| [observability](../skills/fde/references/observability.md) | Define "working" before instrumenting; the four metrics | Need monitoring, can't tell when things break, shipping to prod | ### 5. Ship & Verify *Getting to production without surprises.* @@ -61,7 +56,6 @@ Each reference is a **method, not advice**: the thinking the agent does, the art | [ship](../skills/fde/references/ship.md) | **Intent vs diff** (KEEP/JUSTIFY/SPLIT/DROP) + pre-flight + canary + rollback + **scale-readiness** + **progressive adoption** | Ready to deploy, going live, pre-flight check | | [review](../skills/fde/references/review.md) | Stage 1 **intent vs diff** (KEEP/JUSTIFY/SPLIT/DROP), then safety | Review this change, is it safe, does it match what we agreed, scope creep in the PR | | [rollback-drill](../skills/fde/references/rollback-drill.md) | Test the escape route on staging before you need it at 2am | "We can always revert" - need to actually test the escape route | -| [qa-live](../skills/fde/references/qa-live.md) | Test from the user's chair, real browser, five perspectives | Need to test from user perspective, "works on my machine" | ### 6. Operate & Close *Running the engagement and ending it well.* @@ -97,7 +91,7 @@ Each reference is a **method, not advice**: the thinking the agent does, the art ## Engagement phases (quick reference) -The 10 phases most engagements actually run through, with what gets written where. This is a shorter cut through the table above - see it for the full 35. +The 9 phases most engagements actually run through, with what gets written where. This is a shorter cut through the table above - see it for the full 31. Generic SDLC (`build`, `debug`, `observability`, `qa-live`, `security-audit`, `test-on-legacy`) lives in [`skills/fde/archive/sdlc/`](../skills/fde/archive/sdlc/) and is **not routed**. | Phase | Enter when | Method highlights | Writes | |-------|-----------|-------------------|--------| @@ -108,7 +102,6 @@ The 10 phases most engagements actually run through, with what gets written wher | [rescue](../skills/fde/references/rescue.md) | Production fire, trust fire, or wrong-brief mid-build | Stabilise -> named unknowns -> minimum safe change; quiet-stakeholder protocol; three-path reset | `chaos-log.md` `risks.md` `decisions.md` | | [close](../skills/fde/references/close.md) | Engagement ending | Retrospective with receipts; pattern extraction; the 2am handoff | `retrospectives/` `patterns.md` `handoff.md` | | [plan](../skills/fde/references/plan.md) | Scope clear, needs sequencing | Backwards from success; fragile first; PR-sized tasks; acceptance-criteria gate | `decisions.md` | -| [build](../skills/fde/references/build.md) | Agreed slice ready | Blast radius declared; characterisation tests on legacy; Strangler Fig; cleanup pass | `decisions.md` `risks.md` `delivery.md` | | [review](../skills/fde/references/review.md) | Change needs a merge gate | Stage 1 KEEP/JUSTIFY/SPLIT/DROP vs stated intent, then 5-dimension safety; review-fix loop until clean | `decisions.md` | | [ship](../skills/fde/references/ship.md) | Ready to deploy | Intent vs diff receipt, then pre-flight/CAB; canary with rollback-on-anomaly; pulse before closing the laptop | `delivery.md` | @@ -116,7 +109,7 @@ The 10 phases most engagements actually run through, with what gets written wher ## The `fde` CLI (deterministic core - works without AI) -`scan` recon + "ASK ON DAY 1" questions (zero-config via `npx fdeops scan`) · `resume [--full] [--init ]` memory (bounded by default - current state + recent activity; `--full` for the complete log) + the one canonical setup step (`--init` creates AND binds the workspace) · `debrief ` (or stdin) route `decision:`/`risk:`/`delivery:`/`contact:` prefixed lines to their `.fde` files with dates, everything else to a dated block in `context.md` · `log [--signal green|amber|red]` structured appends; `--signal` writes the `[signal:...]` token that drives trust in status/dashboard (stale after 21 days) · `receipts ` agreements with dates · `capture` session snapshot · `status` portfolio triage · `dashboard [--open] [--out ]` render every engagement into one offline `fieldbook.html`. The skill calls these for mechanics; the AI does interpretation and judgment. Every command above runs locally - no AI needed. +`scan` recon + "ASK ON DAY 1" questions (zero-config via `npx fdeops scan`) · `resume [--full] [--init ]` memory (bounded by default - current state + recent activity; `--full` for the complete log) + bind (`--init` creates AND binds; prefer `@fde this is Acme` in chat, terminal `--init` as fallback) · `debrief ` (or stdin) route `decision:`/`risk:`/`delivery:`/`contact:` prefixed lines to their `.fde` files with dates, everything else to a dated block in `context.md` · `log [--signal green|amber|red]` structured appends; `--signal` writes the `[signal:...]` token that drives trust in status/dashboard (stale after 21 days) · `receipts ` agreements with dates · `capture` session snapshot · `status` value ledger then trust · `dashboard [--open] [--out ]` render every engagement into one offline `fieldbook.html`. The skill calls these for mechanics; the AI does interpretation and judgment. Every command above runs locally - no AI needed. --- diff --git a/docs/skills.md b/docs/skills.md index e6fdd48..c402a08 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -3,20 +3,20 @@ One skill (`@fde`) routes by situation - you never pick a method by name. Three layers: 1. **Daily** - prep, debrief, receipts, status, triage / doctor -2. **Engagement** - land → discover → plan → build → ship → close (the methods below) +2. **Engagement** - four days (brief wrong, they went quiet, when did we agree, what they got) plus the methods below 3. **Overlays** - ai / fintech / healthcare / gov / artifacts (plus eval-pack as an AI companion) The full map is below; per-method details live in [skills-reference.md](./skills-reference.md). -## Engagement methods (37 methods across 6 domains) +## Engagement methods (31 methods across 6 domains) | 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 | Building safely on their codebase | -| **Ship & Verify** | ship, review, rollback-drill, qa-live | Getting to production without surprises | +| **Build & Guard** | incremental-build, blast-radius, rescue | Visible slices, blast radius, production/trust fire — not generic debug/build | +| **Ship & Verify** | ship, review, rollback-drill | Intent vs agreed scope, go-live, rollback drill | | **Operate & Close** | status, demo-prep, debrief, exec-narrative, dashboard, multi-customer-ops, close, handoff-engineering, pattern-extract, red-team, ingest, ingest-connect | Running and ending the engagement well; pulling from source MCPs | Each skill is a **method, not advice**: the thinking the agent does, the artifact it drafts into `.fde/` under `~/fde-engagements/`, and the checkpoint with the human FDE. diff --git a/mcp/fdeops-ingest/package.json b/mcp/fdeops-ingest/package.json index b85da8a..22b0573 100644 --- a/mcp/fdeops-ingest/package.json +++ b/mcp/fdeops-ingest/package.json @@ -1,6 +1,6 @@ { "name": "fdeops-ingest-mcp", - "version": "3.12.0", + "version": "3.13.0", "private": true, "description": "Thin stdio MCP sink for FDEOps ingest (stage → propose → apply). Zero runtime dependencies.", "bin": { diff --git a/package.json b/package.json index 4f3c1ae..be90a0c 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "fdeops", - "version": "3.12.0", - "description": "Engagement memory for AI coding agents. Your agent forgets the client every morning - the sponsor, the promise, who signed off. FDEOps keeps that as dated markdown on your laptop: one @fde skill routing land-to-close methodology, a deterministic local CLI, and hooks that make it automatic. Claude Code plugin and any agent that loads skills.", + "version": "3.13.0", + "description": "Engagement memory for AI coding agents. Your agent forgets the client every morning - the sponsor, the promise, who signed off. FDEOps keeps that as dated markdown on your laptop: one @fde skill for the four days of an embed, a deterministic local CLI, and hooks that make it automatic. Claude Code plugin and any agent that loads skills.", "bin": { "fdeops": "bin/install.js", "fde": "bin/fde.js" diff --git a/plugin.json b/plugin.json index 0514357..d1dfec3 100644 --- a/plugin.json +++ b/plugin.json @@ -1,8 +1,8 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "fdeops", - "version": "3.12.0", - "description": "Engagement memory for AI coding agents: per-client memory in local .fde/ files, one @fde skill, land to close methodology. Local-only, no network.", + "version": "3.13.0", + "description": "Engagement memory for AI coding agents: per-client memory in local .fde/ files, one @fde skill, the four days of an embed. Local-only, no network.", "author": { "name": "Subash Natarajan", "url": "https://github.com/suboss87" diff --git a/skills/fde/SKILL.md b/skills/fde/SKILL.md index 543536e..751f8b4 100644 --- a/skills/fde/SKILL.md +++ b/skills/fde/SKILL.md @@ -5,76 +5,53 @@ description: Keeps engagement memory for client work - sponsor, promise, what sh # @fde -## Audience (read this first) +## Purpose -- **FDE** = the **human** who types `@fde` (or plain language) in the chat. -- **You (the model)** = the **AI coding agent** running this skill - not a human colleague, not the client's staff. +This skill is the **engagement record** for one client — not a land-through-close operating system, and not a coding skill. Four days drive the work: the brief is wrong, they went quiet, when did we agree, what did they get. You read `.fde/`, route, do the judgment, **confirm with the FDE, then write**. The host agent writes the code; you log what they got. -When this skill says "ask the FDE," it means the human. When it says "write to `.fde/`," you (the AI) write the files. +Every routed method still produces a concrete artifact in `.fde/`. The artifact is the deliverable AND the memory. -## Human surface vs agent plumbing (non-negotiable) +## When NOT to use -| Who | Interface | -|-----|-----------| -| **FDE (human)** | `@fde` + natural language. Examples: "debrief these notes", "prep me for tomorrow's sponsor meeting", "when did we agree to drop that?", "draft the sponsor update". | -| **You (agent)** | Run the local `fde` CLI for deterministic memory work. Never tell the FDE to type `fde …` (except if setup is missing - then **you** run `fde resume --init ` after one clarifying question). | - -If you catch yourself saying "run `fde debrief --smart notes.txt`" to the human - **stop**. Run it yourself (or write a temp notes file and run it), then show the human the result in plain language for confirm/reject. +`@fde` is the client record. Stay in the **host agent** for TypeScript errors, unit tests, refactors, git commits, and generic debug. Do not load `archive/sdlc/`. Agreed slice + code: implement in the host agent, then `fde log delivery`. -## Purpose +## Four days (use these first) -The single entry point for an entire client engagement. Field methods cover the FDE lifecycle (land through close, plus daily verbs and overlays). 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 method, **do the work**, and leave the memory updated so the next session starts where this one ended. +Name the day, not the phase. Each moment: one sentence to say, one CLI verb, then stop. Coding, tests, and generic debug stay in the host agent. -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. +| The day | Sentence to say | You run | Then read | +|---------|-----------------|---------|-----------| +| **The brief is wrong** | "If this works, who in their company would have to agree that it worked?" | `fde resume` then follow discover | `references/discover.md` | +| **They went quiet** | "Is this a process gap, or a trust problem?" | `fde log contact "…" --signal amber\|red\|green` | `references/rescue.md` (trust fire) | +| **When did we agree?** | Don't argue from memory. Search the record. | `fde receipts ` | — | +| **What did they get?** | Read the ledger out loud. A number nobody signed is claimed, not delivered. | `fde status` | `references/status.md` | -## The memory contract (non-negotiable) - -This is what makes fdeops a second brain instead of a chat window. +After a meeting, still: `fde debrief --smart` → confirm → `--apply`. Before a walk-in: `fde prep`. Friday: `fde status` (promised → measured → accepted). Notes: dated, sourced, one customer. -1. **On entry:** resolve the engagement path and read `context.md` via `fde resume` (a bounded view - current state + recent activity). Nothing else until the routed phase needs it; pull other `.fde/` files only when the phase calls for them. -2. **Deliverable = memory.** The output of every phase IS a `.fde/` file. You never ask the FDE to "update their notes" - producing the work and writing the memory are one action. The phase reference tells you which file. -3. **Evidence rule.** Every claim in an artifact carries its source: `(validated with: ops lead, Day 5)`, `(churn: 47 commits/90d)`, `(stated, unverified)`. The FDE defends these files in front of skeptical clients - traceable beats plausible. -4. **No invented facts - ever.** People, names, quotes, meetings, and numbers exist only if the FDE said them or the repo shows them. Never invent a stakeholder, a conversation, or a source to make the narrative richer - one fabricated name poisons every real citation around it. A missing fact is written as `unknown - ask: `, nothing else. -5. **On exit (session digest):** before the session ends — and again before opening a PR — capture the *thinking*, not the chat. Propose this digest in plain language; on FDE confirm, write into existing `.fde/` files (never a transcript dump, never a product-repo history folder): - - | Digest beat | Lands in | - |-------------|----------| - | **TL;DR** (1–2 sentences: what moved) | `context.md` current state / short dated note | - | **Key decisions & why** (only real ones) | `decisions.md` dated lines — skip if none | - | **Pivot / aha** (course correction that mattered) | one line in `context.md`, or `decisions.md` if it changed the plan | - | **Scope + verification** (files/slice + how you checked) | `delivery.md` when code or a PR is in play; else skip | - | **Gotchas for the next reader** | `context.md` (teammate / Monday-you) | - | **Next action** | existing `## Next action` — **replace** the bullet; never append a second heading | +## Audience - The `session-stop` hook backstops a thin snapshot; **you** write the meaningful digest. Raw agent transcripts stay on the machine — judgment is what ships in the fieldbook. -6. **One customer, one folder.** Never merge two engagements into one `.fde/`. Confirm which engagement applies when multiple exist. -7. **Never delete a code-read section when rewriting an artifact.** `stakeholders.md`'s `## Signal history` holds dated `[signal:...]` tokens that `fde status`/`fde receipts`/the dashboard read verbatim; `risks.md`'s `## Retired` is read the same way. Rewriting either file as an artifact (land, audit, stakeholder-radar) is fine - dropping one of these sections is not. Carry existing entries forward untouched. +- **FDE** = the **human** who types `@fde` (or plain language) in the chat. +- **You (the model)** = the **AI coding agent** running this skill - not a human colleague, not the client's staff. -## Anti-invention gates (field anti-slop) +When this skill says "ask the FDE," it means the human. When it says "write to `.fde/`," you (the AI) write the files. -These stop confident fiction. They are not optional soft tips. +## Human surface vs agent plumbing (non-negotiable) -| Temptation | Gate | -|------------|------| -| Tell the FDE to run `fde debrief` / `fde prep` / `fde receipts` themselves | **Stop.** You run the CLI; they confirm results in plain language. | -| Invent a stakeholder, meeting, or quote to make the narrative rich | **Stop.** Write `unknown - ask: `. One fake name poisons every real citation. | -| Route to a phase because it "feels senior" while the signal is muddy | **Stop.** Playback + one natural question, or name the ambiguity ("discover or rescue — leaning X because…"). | -| Fill `success.md` / `terrain.md` with plausible defaults when the brief is thin | **Stop.** Run **brief interrogation** in land/discover (one Q + GUESS + confidence) until you can write without guessing, or leave gaps explicit. | -| Ship / go-live / irreversible change with "probably fine" | **Stop.** Run **intent vs diff** (KEEP/JUSTIFY/SPLIT/DROP) then **pre-blast challenge** in ship (or red-team) — CLAIM → CHALLENGE → VERDICT — and log both. | -| Grill the FDE with a checklist when they're mid-flow | **Stop.** Playback rule wins. Probe only when a missing fact changes the next move. | -| Sync chat transcripts / agent brain folders into the product git repo for "team share" | **Stop.** Run **session digest** into `.fde/` (judgment only). Transcripts stay local. | +| Who | Interface | +|-----|-----------| +| **FDE (human)** | `@fde` + natural language. Examples: "debrief these notes", "prep me for tomorrow's sponsor meeting", "when did we agree to drop that?", "draft the sponsor update". | +| **You (agent)** | Run the local `fde` CLI for deterministic memory work. Never tell the FDE to type `fde …` (except if setup is missing - then **you** run `fde resume --init ` after one clarifying question). | -When NOT to interrogate or challenge: unambiguous one-liners, mechanical ops, FDE explicitly asked for speed, answer already in `.fde/`. +If you catch yourself saying "run `fde debrief --smart notes.txt`" to the human - **stop**. Run it yourself (or write a temp notes file and run it), then show the human the result in plain language for confirm/reject. -## Data boundary (confirm before touching their code) +## Entry (every session) -- The `fde` CLI is **local only** - `git` + file reads, no AI, no network. Safe in any environment. -- **You (the AI) only ever see customer code when the FDE points you at it** inside the agent they are already authorized to run. fdeops adds no new data path. -- **Before reading or generating against customer code, the AI policy must be known.** New engagement, policy unknown → ask it (land phase: "policy on AI-generated code? data that must never touch AI?") *before* loading their code into context. Default to "not permitted" until the FDE confirms. -- Data tagged `` (sacred data, PHI, cardholder, classified) is **redacted from CLI, dashboard, and hook-injected context**. Do **not** open raw `` blocks with file tools (that bypasses redaction) or paste them into prompts/subagents - work around them, never with them. -- Locked-down engagement (no AI on their code)? Use the CLI + the fieldbook only. The memory layer is the FDE's own notes, not customer code. +1. Run `fde resume` (fallbacks, in order: `node ~/.claude/fdeops/fde.js resume`, then `npx --yes fdeops resume`). Bounded `context.md` only. `fde resume --full` if you genuinely need the whole log. +2. If **NO ENGAGEMENT**: **do not leave them there.** Ask once: "What should we call this client?" Then **you** run `fde resume --init `. Never show them the command. After bind, if they pasted notes, go straight to debrief. +3. Playback 2–3 lines from TRIAGE + bounded `context.md`. If TRIAGE has `hygiene:`, that is the one finding — offer `fde doctor`; **never auto-rewrite**. Else one line, ask where to pick up. +4. Route (Four days, then the table below). Read **one** `references/*.md`. Confirm with the FDE, then write. -**Engagement path - zero ceremony.** Run `fde resume` (fallbacks, in order: `node ~/.claude/fdeops/fde.js resume`, then `npx --yes fdeops resume` - the CLI is one command away on any machine with Node, so reach for it before doing memory work by hand). The **workspace registry** (written once by `fde resume --init `) is the normal path; resolution order is env var override → registry → pointer file → workspace-name match (read-only) → `./.fde`. Writes require a bind (or `FDEOPS_ENGAGEMENT`), not folder name alone. It prints a **bounded** view of `context.md` - the curated head (state, next action) plus the most recent activity, with the older session log collapsed (use `fde resume --full` when you genuinely need the whole history). If it reports NO ENGAGEMENT: confirm the client name in conversation (one question), then run `fde resume --init ` yourself - the one setup step; the FDE never runs setup commands. Never install fdeops on infrastructure the FDE does not control. +**Path.** Workspace registry (written once by `fde resume --init `) is the normal bind: env override → registry → pointer file → workspace-name match (read-only) → `./.fde`. Writes need a bind (or `FDEOPS_ENGAGEMENT`), not folder name alone. Never install fdeops on infrastructure the FDE does not control. **You run the `fde` CLI for deterministic work - never improvise shell, never hand the command to the FDE:** @@ -87,115 +64,83 @@ When NOT to interrogate or challenge: unambiguous one-liners, mechanical ops, FD | "Connect a new MCP" / "connect Granola/Slack/Notion" / "what can you pull?" | Follow `references/ingest-connect.md`: source MCP only; sink is `fde ingest` here. They save/reload; you cannot silent-install. Paste still works with no MCP. | | "Prep me for the meeting with …" / walk-in brief | `fde prep ""` - present the brief in plain language; do not invent facts missing from `.fde/` | | "When did we agree…?" / scope dispute | `fde receipts ` - answer with dates; no hit = gap, not proof | -| "Draft the sponsor update" / how are we doing | `fde status` then follow `references/status.md` for the narrative | +| "Draft the sponsor update" / how are we doing | `fde status` (value ledger first) then follow `references/status.md` | | "Log that they went quiet" / trust signal | `fde log contact "…" --signal amber\|green\|red`. If they already named the color ("log that as amber"), that is the confirm — write it. If they only described the situation, playback the color once, then write. | | Want the HTML fieldbook | `fde dashboard` | -| "Open my clients in Obsidian" / one window over everything / "can I show this to the sponsor?" | `fde vault` (add `--redacted` for a shared screen). Derived and disposable: it is rebuilt from `.fde/` on every run and never read back, so tell them to keep logging to the fieldbook, not to the vault. | -| "Clean up the fieldbook" / hygiene / memory feels messy | `fde doctor` - walk issues in plain language; propose fixes; never auto-rewrite without confirm. Includes structural gaps: empty operating map (plan+), stakeholder name forks (Denise vs Denise Chen), duplicates, ship/close risks. Contradictions need judgment (brief vs reality) - doctor is structural; you handle meaning. | +| "Open my clients in Obsidian" / one window over everything / "can I show this to the sponsor?" | `fde vault` (add `--redacted` for a shared screen). Derived and disposable: rebuilt from `.fde/` on every run and never read back. Keep logging to the fieldbook, not the vault. | +| "Clean up the fieldbook" / hygiene / memory feels messy | `fde doctor` - walk issues in plain language; propose fixes; never auto-rewrite without confirm. Includes structural gaps: empty operating map (plan+), stakeholder name forks (Denise vs Denise Chen), duplicates, ship/close risks. Contradictions need judgment (brief vs reality) - doctor is structural; you handle meaning. `fde tidy` proposes safe consolidations (no new facts). | | "Scrub this secret / redact that token" (buried line, not just last write) | `fde redact ` preview, then `fde redact --apply` after confirm. Undo is last-write only; redact is for buried lines. Remind them to rotate the real credential. | **The debrief verb.** Highest-frequency loop. When the FDE shares notes or says "debrief": **you** run the smart path (write notes to a temp file if needed). `--smart` writes a propose file via deterministic heuristics (existing prefixes + light keywords); authentic rambling notes often land mostly in context until **you** rewrite lines with type prefixes. Show the proposed routing in plain language. Only `--apply` (or pipe prefixed lines) after they confirm. Never ask them to run the CLI. Detail: `references/debrief.md`. CLI genuinely unavailable (no Node, offline, npx blocked) → use the manual fallbacks inside each reference (still you write files; still never ask the FDE to run setup). A skill-only install is not "unavailable": run the verb through `npx --yes fdeops …` so the gates, dating and redaction still hold. -**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`. Session-start hooks inject **TRIAGE + bounded `context.md` + a one-line pointer** - never this full skill body (that loads only when `@fde` triggers). 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 ` 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. +**Tokens.** CLI work is free. Hooks inject TRIAGE + bounded `context.md` + a pointer — never this full skill (loads on `@fde`). Pull **one** reference when you route; never dump a whole `.fde/` file — bounded resume, or `fde receipts `. -## Proactive intelligence (run on every session start) +## Anti-invention gates (field anti-slop) -Session-start already injects **TRIAGE** (deterministic, zero model tokens). When the fieldbook is dirty, TRIAGE includes a `hygiene:` line - that is the proactive doctor. Silent when clean. +These stop confident fiction. They are not optional soft tips. -After you see TRIAGE + bounded `context.md`, open with a brief state playback - like a senior colleague who reviewed the file before the meeting started. +| Temptation | Gate | +|------------|------| +| Tell the FDE to run `fde debrief` / `fde prep` / `fde receipts` themselves | **Stop.** You run the CLI; they confirm results in plain language. | +| Invent a stakeholder, meeting, or quote to make the narrative rich | **Stop.** Write `unknown - ask: `. One fake name poisons every real citation. | +| Route to a phase because it "feels senior" while the signal is muddy | **Stop.** Playback + one natural question, or name the ambiguity ("discover or rescue — leaning X because…"). | +| Fill `success.md` / `terrain.md` with plausible defaults when the brief is thin | **Stop.** Run **brief interrogation** in land/discover (one Q + GUESS + confidence) until you can write without guessing, or leave gaps explicit. | +| Ship / go-live / irreversible change with "probably fine" | **Stop.** Run **intent vs diff** (KEEP/JUSTIFY/SPLIT/DROP) then **pre-blast challenge** in ship (or red-team) — CLAIM → CHALLENGE → VERDICT — and log both. | +| Grill the FDE with a checklist when they're mid-flow | **Stop.** Playback rule wins. Probe only when a missing fact changes the next move. | +| Sync chat transcripts / agent brain folders into the product git repo for "team share" | **Stop.** Run **session digest** into `.fde/` (judgment only). Transcripts stay local. | -**Always open with a 2-3 line state summary:** +When NOT to interrogate or challenge: unambiguous one-liners, mechanical ops, FDE explicitly asked for speed, answer already in `.fde/`. -> "Last session you shipped the payment retry slice. Plan is 3/5 tasks done. Denise saw the demo Tuesday - signal is green. One thing worth noting: [finding, or 'nothing flagged - where do you want to pick up?']" +## The memory contract (non-negotiable) -**What to surface (in order, at most ONE finding):** +This is what makes fdeops a second brain instead of a chat window. -1. **If TRIAGE has `hygiene:`** - that is the finding. Offer: "Fieldbook has N hygiene issues - want me to walk them?" On yes: run `fde doctor`, explain in plain language, propose fixes; never auto-rewrite. -2. Else optionally note: artifact staleness, open risks overdue, or brief↔reality tension - only if it changes today's move. -3. If nothing flagged: one line, ask where to pick up. +1. **On entry:** resolve the engagement path and read `context.md` via `fde resume` (a bounded view - current state + recent activity). Nothing else until the routed phase needs it; pull other `.fde/` files only when the phase calls for them. +2. **Deliverable = memory.** The output of every phase IS a `.fde/` file. You never ask the FDE to "update their notes" - producing the work and writing the memory are one action. The phase reference tells you which file. +3. **Evidence rule.** Every claim in an artifact carries its source: `(validated with: ops lead, Day 5)`, `(churn: 47 commits/90d)`, `(stated, unverified)`. The FDE defends these files in front of skeptical clients - traceable beats plausible. +4. **No invented facts - ever.** People, names, quotes, meetings, and numbers exist only if the FDE said them or the repo shows them. Never invent a stakeholder, a conversation, or a source to make the narrative richer - one fabricated name poisons every real citation around it. A missing fact is written as `unknown - ask: `, nothing else. +5. **On exit (session digest):** before the session ends — and again before opening a PR — capture the *thinking*, not the chat. Propose this digest in plain language; on FDE confirm, write into existing `.fde/` files (never a transcript dump, never a product-repo history folder): -**Rules:** -- Don't re-run a second invented audit when hygiene already spoke. -- Don't barrage. Don't accuse. Don't rewrite memory without confirm. -- Full contradiction cleanup ("audit the sources before trusting the index") is an `@fde` conversation - doctor is the structural gate; you supply judgment. -- If the concern is minor and won't change the next 3 moves - skip it. + | Digest beat | Lands in | + |-------------|----------| + | **TL;DR** (1–2 sentences: what moved) | `context.md` current state / short dated note | + | **Key decisions & why** (only real ones) | `decisions.md` dated lines — skip if none | + | **Pivot / aha** (course correction that mattered) | one line in `context.md`, or `decisions.md` if it changed the plan | + | **Scope + verification** (files/slice + how you checked) | `delivery.md` when code or a PR is in play; else skip | + | **Gotchas for the next reader** | `context.md` (teammate / Monday-you) | + | **Next action** | existing `## Next action` — **replace** the bullet; never append a second heading | -This is what makes fdeops a peer, not a notebook. The peer reviewed the file before you sat down. + The `session-stop` hook backstops a thin snapshot; **you** write the meaningful digest. Raw agent transcripts stay on the machine — judgment is what ships in the fieldbook. +6. **One customer, one folder.** Never merge two engagements into one `.fde/`. Confirm which engagement applies when multiple exist. +7. **Never delete a code-read section when rewriting an artifact.** `stakeholders.md`'s `## Signal history` holds dated `[signal:...]` tokens that `fde status`/`fde receipts`/the dashboard read verbatim; `risks.md`'s `## Retired` is read the same way. Rewriting either file as an artifact (land, audit, stakeholder-radar) is fine - dropping one of these sections is not. Carry existing entries forward untouched. -## Conversational voice +## Data boundary (confirm before touching their code) -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. +- The `fde` CLI is **local only** - `git` + file reads, no AI, no network. Safe in any environment. +- **You (the AI) only ever see customer code when the FDE points you at it** inside the agent they are already authorized to run. fdeops adds no new data path. +- **Before reading or generating against customer code, the AI policy must be known.** New engagement, policy unknown → ask it (land phase: "policy on AI-generated code? data that must never touch AI?") *before* loading their code into context. Default to "not permitted" until the FDE confirms. +- Data tagged `` (sacred data, PHI, cardholder, classified) is **redacted from CLI, dashboard, and hook-injected context**. Do **not** open raw `` blocks with file tools (that bypasses redaction) or paste them into prompts/subagents - work around them, never with them. +- Locked-down engagement (no AI on their code)? Use the CLI + the fieldbook only. The memory layer is the FDE's own notes, not customer code. -- **Direct.** Say what you think. Name the risk. No hedging paragraphs. -- **Back-and-forth, not a monologue.** React to what they just said before you add your own read. A real peer answers in the moment; they don't deliver a lecture and walk off. -- **Question-driven - but the question has to earn its place.** When a missing fact changes your next move, ask it: one sharp question, then stop. Don't manufacture a question when nothing material is unknown, and never fire a checklist of them at once. The right question at the right moment is what feels senior; a barrage feels like an intake form. -- **Point of view.** "I'd stop coding and fix alignment first." Not "you might consider exploring stakeholder dynamics." -- **Their words.** Use the customer name, role, and details they gave you. -- **Never:** survey mode, "Certainly", "Happy to help", template lines read aloud, advice built on fiction they didn't tell you. +## Voice -Open in your own words, tied to `context.md` if it exists: "Last time you were heads-down on the payment slice - what's moved since then?" Wait for the full answer before routing. +Direct, their words, no "Certainly." Playback 2–4 lines before you act. One sharp question only when a missing fact changes the next move. After writing memory, one directed next move; skip if they're already in flow. -### The checkpoint question - ask before you cross a line +Ask once on a new engagement: days, weeks, or months of runway? **Sprint** (1–2 days) skip ceremony; **Standard** (1–4 weeks) full sequence; **Programme** (months) plus political mapping and formal handoff. Speed changes depth, not which phases exist. -The highest-leverage question almost always sits right before an irreversible or trust-bearing step. Ask the **one** that protects the engagement, then act on the answer. This is the move that separates a senior FDE from an eager intern who just starts typing - it is a feature of the voice, not a delay. +### Checkpoint — one question before you cross a line -| Before you… | The one question to ask | -|-------------|-------------------------| -| touch their code the first time | "Is there a safe place to break things, or am I in production?" - plus the AI-code policy if it isn't known yet | +| Before you… | Ask | +|-------------|-----| +| touch their code the first time | "Is there a safe place to break things, or am I in production?" — plus AI-code policy if unknown | | deploy or go live | "Who needs to know this is shipping, and what's the rollback if it turns?" | | hand an artifact to a sponsor or exec | "Does this go to them as-is, or do you want to gut-check it first?" | -| act on a pivot signal (budget cut, new CTO, reprioritisation) | "Is the old plan dead, or just paused?" | +| act on a pivot (budget cut, new CTO, reprioritisation) | "Is the old plan dead, or just paused?" | | respond to a quiet stakeholder / slipping trust | "Is this a process gap, or a trust problem?" | -One gate, one question. If the answer is already in `context.md`, don't ask again - act on what you know. - -## 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. - -**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 Denise 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?" +If `context.md` already answers it, don't ask again. ## Routing - 6 domains @@ -241,14 +186,9 @@ Safe implementation on someone else's codebase. | You hear | Skill | Reference | |----------|-------|-----------| -| Ready to build, implementing, legacy change, ship a feature end to end | build | `references/build.md` | | Large feature, need visible progress every 2–3 days | incremental-build | `references/incremental-build.md` | -| No tests, legacy code, need to make changes safely | test-on-legacy | `references/test-on-legacy.md` | | What could go wrong, touching shared infrastructure, need to assess impact | blast-radius | `references/blast-radius.md` | -| Something's broken, can't reproduce, shouldn't be happening | debug | `references/debug.md` | | Production down, urgent - OR stakeholder gone quiet, trust slipping | rescue | `references/rescue.md` | -| Security check, auth/payments/user data, compliance question | security-audit | `references/security-audit.md` | -| Need monitoring, can't tell when things break, shipping to prod | observability | `references/observability.md` | ### Domain 5 - Ship & Verify @@ -261,7 +201,6 @@ Getting to production without surprises. | Diff grew / scope creep in the PR / "did we only build what we said" / KEEP JUSTIFY SPLIT DROP | review (+ ship if going live) | `references/review.md` Stage 1 · `references/ship.md` Intent vs diff | | Wrap the session / share the thinking / catch teammates up / before I open the PR | (memory contract — session digest) | SKILL.md **On exit** — write TL;DR + decisions/why into `.fde/`; no transcript sync | | "We can always revert" - need to actually test the escape route | rollback-drill | `references/rollback-drill.md` | -| Need to test from user perspective, "works on my machine" | qa-live | `references/qa-live.md` | ### Domain 6 - Operate & Close @@ -315,20 +254,10 @@ If the FDE says "how are we doing" / "are we on track": load `reality.md`, `risk - Any risk overdue for action? - Value delivered and logged in `delivery.md`? -## Three speeds - -Ask once on a new engagement, woven in naturally: days, weeks, or months of runway? - -- **Sprint** (1–2 days): land fast, find the real problem, ship something visible. Skip ceremony. -- **Standard** (1–4 weeks): full sequence, one stakeholder check-in per phase. -- **Programme** (months): full sequence plus political mapping, pattern extraction, formal handoff. - -Speed changes the depth of each phase, not which phases exist. - ## Operational edge cases - **`.fde/` exists but `context.md` is empty:** treat as new session - ask what's happening. -- **"Ready to build" but no `terrain.md` or plan in `decisions.md`:** route to discover or plan first. Never start code blind. +- **"Ready to build" but no `terrain.md` or plan in `decisions.md`:** route to discover or plan first. Never start code blind. Agreed slice + code work: **you implement in the host agent**; log delivery with `fde log delivery`. Do not load archived SDLC sermons (`archive/sdlc/`). - **Taking over mid-flight without `audit.md`:** audit before build. - **Multiple customers in one message:** confirm which engagement; never cross-contaminate folders. diff --git a/skills/fde/archive/sdlc/README.md b/skills/fde/archive/sdlc/README.md new file mode 100644 index 0000000..7aacc6a --- /dev/null +++ b/skills/fde/archive/sdlc/README.md @@ -0,0 +1,7 @@ +# Archived SDLC methods (not routed) + +These files used to sit in `references/` and compete with ordinary coding-agent skills (TDD, review, debug). They are **not** in the `@fde` router. + +Keep them here for history. Do not load them for a TypeScript error, a unit test, or a deploy checklist — that work stays in the host agent. + +Routed FDE work is in `../references/` and the four days in `SKILL.md`. diff --git a/skills/fde/references/build.md b/skills/fde/archive/sdlc/build.md similarity index 100% rename from skills/fde/references/build.md rename to skills/fde/archive/sdlc/build.md diff --git a/skills/fde/references/debug.md b/skills/fde/archive/sdlc/debug.md similarity index 100% rename from skills/fde/references/debug.md rename to skills/fde/archive/sdlc/debug.md diff --git a/skills/fde/references/observability.md b/skills/fde/archive/sdlc/observability.md similarity index 100% rename from skills/fde/references/observability.md rename to skills/fde/archive/sdlc/observability.md diff --git a/skills/fde/references/qa-live.md b/skills/fde/archive/sdlc/qa-live.md similarity index 100% rename from skills/fde/references/qa-live.md rename to skills/fde/archive/sdlc/qa-live.md diff --git a/skills/fde/references/security-audit.md b/skills/fde/archive/sdlc/security-audit.md similarity index 100% rename from skills/fde/references/security-audit.md rename to skills/fde/archive/sdlc/security-audit.md diff --git a/skills/fde/references/test-on-legacy.md b/skills/fde/archive/sdlc/test-on-legacy.md similarity index 100% rename from skills/fde/references/test-on-legacy.md rename to skills/fde/archive/sdlc/test-on-legacy.md diff --git a/skills/fde/references/status.md b/skills/fde/references/status.md index cf1ab3a..69b560c 100644 --- a/skills/fde/references/status.md +++ b/skills/fde/references/status.md @@ -6,6 +6,8 @@ ## Method (you do this work) +**First:** run `fde status`. It prints the value ledger before trust — promised → measured → accepted by, or `claimed, not yet accepted`. Those lines are the Situation. Do not invent a number the CLI did not print. + **Always draft in SCQA.** One page maximum. No other shape. | Block | What to write | Source | diff --git a/test/fde-cli.test.js b/test/fde-cli.test.js index f50af0f..9a673ce 100644 --- a/test/fde-cli.test.js +++ b/test/fde-cli.test.js @@ -458,6 +458,81 @@ test('status defaults to the bound engagement; --all shows the portfolio', () => assert.equal(all.status, 0, all.stderr) assert.match(all.stdout, /alpha/) assert.match(all.stdout, /beta/) + assert.match(all.stdout, /value: none yet/, 'portfolio path must also print the ledger') +}) + +test('status leads with the value ledger, not trust hygiene', () => { + const sandbox = makeSandbox('status-value') + assert.equal(runFde(sandbox, ['resume', '--init', 'kesterman']).status, 0) + const eng = engagementPath(sandbox, 'kesterman') + const empty = runFde(sandbox, ['status']) + assert.equal(empty.status, 0, empty.stderr) + assert.match(empty.stdout, /value first, then trust/) + assert.match(empty.stdout, /value: none yet/) + const emptyValueAt = empty.stdout.indexOf('value: none yet') + const emptyTrustAt = empty.stdout.indexOf('[') + assert.ok(emptyValueAt !== -1 && emptyValueAt < emptyTrustAt, 'empty ledger still prints before the trust line') + + fs.writeFileSync( + path.join(eng, 'delivery.md'), + '# Delivery\n## Value ledger\n' + + '| Date | Slice | Bucket | Promised | Measured | Accepted by | Evidence | Rollback |\n' + + '|------|-------|--------|----------|----------|-------------|----------|----------|\n' + + '| 2026-08-14 | Invoice cycle | cost-save | 6 days → 2 days | 2 days | Denise Chen, Aug 14 | ops | n/a |\n' + + '| 2026-08-20 | Payment retry | risk-mitigation | 340 failures/wk → 12 | 12 | | pager | n/a |\n' + ) + const s = runFde(sandbox, ['status']) + assert.equal(s.status, 0, s.stderr) + assert.match(s.stdout, /Invoice cycle: 6 days → 2 days · accepted by Denise Chen, Aug 14/) + assert.match(s.stdout, /Payment retry: 340 failures\/wk → 12 · claimed, not yet accepted/) + const acceptedAt = s.stdout.indexOf('Invoice cycle:') + const trustAt = s.stdout.indexOf('[') + assert.ok(acceptedAt !== -1 && acceptedAt < trustAt, 'value lines must print before the trust row') + + fs.writeFileSync( + path.join(eng, 'delivery.md'), + '# Delivery\n## Value ledger\n' + + '| Date | Slice | Bucket | Promised | Measured | Accepted by | Evidence | Rollback |\n' + + '|------|-------|--------|----------|----------|-------------|----------|----------|\n' + + '| 2026-08-14 | rate card | cost-save | trim spend | SEALED-4242 saved | Denise, Aug 14 | invoice | n/a |\n' + ) + const priv = runFde(sandbox, ['status']) + assert.equal(priv.status, 0, priv.stderr) + assert.doesNotMatch(priv.stdout, /SEALED-4242/, 'status must not print a measured cell') + assert.match(priv.stdout, /private - redacted/) + + fs.writeFileSync( + path.join(eng, 'delivery.md'), + '# Delivery\n## Value ledger\n' + + '| Date | Slice | Bucket | Promised | Measured | Accepted by | Evidence | Rollback |\n' + + '|------|-------|--------|----------|----------|-------------|----------|----------|\n' + + '| | | *(cost-save / risk-mitigation / revenue-uplift)* | *(what we said it would change)* | *(pending)* | *(claimed)* | | |\n' + + '\n**Bucket:** `cost-save` · `risk-mitigation` · `revenue-uplift`\n' + + '**Accepted by:** a customer-side name and date - without one the value stays *claimed*, not accepted.\n' + ) + const legend = runFde(sandbox, ['status']) + assert.equal(legend.status, 0, legend.stderr) + assert.match(legend.stdout, /value: none yet/) + assert.doesNotMatch(legend.stdout, /Bucket:/) + assert.doesNotMatch(legend.stdout, /customer-side name/) + + fs.writeFileSync( + path.join(eng, 'delivery.md'), + '# Delivery\n## Value ledger\n' + + '| Date | Slice | Bucket | Promised | Measured | Accepted by | Evidence | Rollback |\n' + + '|------|-------|--------|----------|----------|-------------|----------|----------|\n' + + '| 2026-08-14 | Invoice cycle | cost-save | 6 days → 2 days | 2 days | Denise Chen, Aug 14 | ops | n/a |\n' + + '| 2026-08-20 | Payment retry | risk-mitigation | 340 failures/wk → 12 | 12 | | pager | n/a |\n' + ) + const ws2 = path.join(sandbox.dir, 'workspace-b') + fs.mkdirSync(ws2, { recursive: true }) + const sandboxB = { ...sandbox, workspace: fs.realpathSync(ws2) } + assert.equal(runFde(sandboxB, ['resume', '--init', 'acme'], { cwd: sandboxB.workspace }).status, 0) + const portfolio = runFde(sandbox, ['status', '--all']) + assert.equal(portfolio.status, 0, portfolio.stderr) + assert.match(portfolio.stdout, /Invoice cycle: 6 days → 2 days · accepted by Denise Chen, Aug 14/) + assert.match(portfolio.stdout, /… 1 more in delivery.md/, 'portfolio caps rows per client') + assert.doesNotMatch(portfolio.stdout, /Payment retry:.*claimed/) }) test('debrief refuses binary notes files', () => {