fdeops 3.26.0 → 3.27.1

package/README.md

@@ -1,244 +1,139 @@
 # FDEOps
 
-**One client record, from first meeting to handover.**
+**Forward deployed engineering skills for AI coding agents.**
 
-FDEOps helps a Forward Deployed Engineer or independent expert manage client work with an AI coding agent. Keep the brief, decisions, delivery evidence, acceptance, and next actions together across repositories and sessions.
+Your agent writes code. FDEOps helps you deliver the client work around it: understand the problem, agree what done means, prove the result, and hand it over.
 
-One `@fde` skill guides the work. A local CLI records it in Markdown. A read-only dashboard shows one client or your portfolio. You review judgments and obtain customer approval; the tool does not decide for them.
+<a name="who-this-is-for"></a>
 
-<img width="1536" height="1024" alt="fdeops" src="https://github.com/user-attachments/assets/2bcb8739-55ee-445d-8a1a-8b38433b7b58" />
+An open-source kit for FDEs, independent consultants, and small agencies working across client projects. Use it with your coding agent. Keep a separate record for each client on your own laptop.
 
----
+[Install](#quick-start) · [See the dashboard](#your-daily-fieldbook) · [Documentation](docs/README.md)
 
-## Quick Start
+<img width="960" height="640" alt="FDEOps: forward deployed engineering from the first client meeting to handover" src="https://github.com/user-attachments/assets/2bcb8739-55ee-445d-8a1a-8b38433b7b58" />
 
-**Inspect a repository first.** Requires Node.js 18+ and Git. Run from a local repository:
+## Why use it?
 
-```bash
-npx fdeops scan
-```
+- **Pick up where you left off.** The brief, decisions, risks, and next action travel with the client record, across sessions and agents.
+- **Know what you can stand behind.** Keep what was promised, what was measured, and what the customer accepted separate, with evidence for each result.
+- **See what needs you today.** An offline dashboard shows the next step and missing evidence, measurement, or approval across your clients.
 
-`npx` may download the package. The scan itself reads local files, prints reconnaissance and questions, and does not write engagement records.
+## Quick Start
 
-**Then install the skill:**
+Requires Node.js 18+, Git, and an AI coding agent that supports skills. Install the FDEOps skill:
 
 ```bash
 npx skills add suboss87/fdeops --skill fde
 ```
 
-One chat. Name the client:
+Open a client workspace and tell your agent:
 
 ```text
 @fde this is client01
 ```
 
-The agent creates and binds `~/fde-engagements/client01/.fde/` to the workspace. Paste kickoff notes; review the proposed decisions, risks, and next actions before saving. If setup cannot run in your host, use `npx fdeops resume --init client01` to create the engagement and binding.
-
-Open the engagement fieldbook anytime:
-
-```bash
-npx fdeops dashboard --open
-```
-
-Read-only HTML of the record - promised, measured, accepted, and evidence. Regenerate after you change memory. Day to day: [docs/USAGE.md](docs/USAGE.md).
-
-<details>
-<summary><b>Claude Code</b></summary>
-
-```text
-/plugin marketplace add suboss87/fdeops
-/plugin install fdeops@fdeops
-```
-
-The plugin registers Claude Code session hooks and slash commands. A skill-only install does not register hooks.
+The agent creates `~/fde-engagements/client01/.fde/` on your laptop and links the workspace to that client. Paste the brief or meeting notes into the same conversation. `@fde` works through the situation with you; you review the proposed record before it is applied.
 
-</details>
+**Claude Code plugin or another host?** Follow the [installation guide](docs/install.md). It explains hooks, adapters, offline setup, and the CLI fallback if your agent cannot run setup. Skill-only installation does not add automatic session hooks.
 
-<details>
-<summary><b>Cursor</b></summary>
-
-After the skill install, in the **client repo** you have open (pointer, not a second pack):
+**Try it without an AI model:**
 
 ```bash
-npx fdeops adapters .
+npx fdeops demo
 ```
 
-See [adapters/](adapters/README.md).
+The demo runs fictional notes through review, applies them in a sandbox, and prints a fieldbook path to open. It writes and resets only its demo folder under `~/fde-engagements/.demo/`. Remove the demo with `npx fdeops demo --clean`. `npx` may download packages; the FDEOps CLI itself works locally.
 
-</details>
+⭐ **If FDEOps makes your client work easier, star the repo.**
 
-<details>
-<summary><b>Clone install and offline use</b></summary>
+## What a working day looks like
 
-```bash
-git clone https://github.com/suboss87/fdeops.git
-cd fdeops
-node bin/install.js
-```
+You come out of a meeting with this:
 
-If the agent cannot create the folder:
-
-```bash
-npx fdeops resume --init client01   # ~/fde-engagements/client01
+```text
+@fde Mara wants CSV upload first. Devon asked for ERP sync,
+but Mara has not approved that scope. The staging replay took
+five minutes; production has not been measured. Ask Mara for
+staging access before Friday. Source: kickoff meeting, 10 September.
 ```
 
-For offline use, transfer the checkout first; cloning and package downloads need network access. Override: `FDEOPS_ENGAGEMENT`. See [docs/install.md](docs/install.md).
-
-</details>
-
----
-
-## Commands
-
-One command per stage. Skills load automatically.
-
-Six stages organize the engagement: Land, Discover, Plan, Ship, Outcome, Close. Start with the current situation; revisit earlier decisions when the evidence changes. Slash commands below are provided by the Claude Code plugin. In other hosts, describe the same request to `@fde`.
-
-| What you're doing | Command | Stage |
-|-------------------|---------|-------|
-| First days. Get the brief. Name who signs. | `/brief` | Land |
-| Check the brief is the real job. | `/discover` | Discover |
-| Sequence from done, not from the ticket. | `/plan` | Plan |
-| Prove it on their staging, then go live. | `/ship` | Ship |
-| What you promised, measured, and who accepted. | `/outcome` | Outcome |
-| Hand it over. They run it without you. | `/close` | Close |
-
-Same `@fde`, when you need them: `/debrief` (notes into the record), `/prep` (one page before you walk in), `/trust` (process gap, or they stopped trusting you), `/receipts` (a dated line, or it did not happen), `/readout` (Friday page for the sponsor; not a seventh stage).
+The agent shows you what changed, what was only requested, what is still unknown, and what happens next. You correct it and confirm the update. A request does not become agreed scope. A staging result does not become a production result. Naming a signer does not mean they accepted the work.
 
-You can also describe the situation in plain English: a new client, a POC, an incident, a scope change, or a question about what was agreed.
+Tomorrow, `@fde` resumes from that record. Before a sponsor meeting, ask what was promised, what was measured, and where the proof is. When someone takes over, give them the handoff packet.
 
----
+[Walk through notes → REVIEW → apply → evidence](docs/USAGE.md#new-here-5-minutes).
 
 ## Your daily fieldbook
 
-![FDEOps dark dashboard showing next actions and attention gaps across three fictional clients](media/fieldbook-preview.png)
-
-*Fictional client records, shown in the built-in dark theme. The report works offline.*
-
-Read [verification results and limits](docs/verification.md) for context measurements, local-model observations, and MCP coverage.
-
-Open `npx fdeops dashboard --all --open` to review every client. Filter what needs attention, open a client, and copy **Continue next action** into your agent. After a meeting, use **Debrief notes**; before a sponsor update, use **Review outcome**. These buttons copy prompts; work runs in your agent. Review changes there and regenerate the dashboard afterward.
-
-## Try the complete loop
+![Dark FDEOps fieldbook with one recommended action per client and the gaps behind it](media/fieldbook-preview.png)
 
 ```bash
-npx fdeops demo
-```
-
-This writes fictional records and HTML under `~/fde-engagements/.demo/`, resetting its own sandbox on each run. It requires no AI account. Open the generated report; remove the demo later with `npx fdeops demo --clean`. Follow the [five-minute walkthrough](docs/USAGE.md#new-here-5-minutes) for what to inspect.
-
-
----
-
-## All 30 Skills
-
-Not prompts to choose from: the router loads one relevant skill with concrete steps, an artifact, and a checkpoint. The [skills reference](docs/skills-reference.md) lists all 30, from discovery and scope control to incident response and handover. Industry and AI overlays apply when relevant.
-
-Optional external sources use your configured MCP connections. The agent pulls on request, stages the material, and asks you to review its interpretation before applying it. The CLI itself stays local. See [source recipes](mcp/recipes/) and [ingest usage](docs/USAGE.md#ingest-pull-large-artifacts--same-confirm-loop).
-
----
-
-## How Skills Work
-
-One `@fde`. One file per situation. One folder per client.
-
+npx fdeops dashboard --open         # current client
+npx fdeops dashboard --all --open   # all clients
 ```
-  "@fde this is client01"      creates ~/fde-engagements/client01/.fde/
-  /brief  or  English          the AI coding agent loads skills/fde/SKILL.md
-           │  routes. you never pick a skill by name
-           ▼
-  references/<one>.md          one skill, then stop
-           │
-           ▼
-  fde CLI (local)              dates, gates, redacts. no network
-           │  after you confirm
-           ▼
-  ~/fde-engagements/client01/.fde/
-           │
-           ▼
-  fde dashboard --open         offline fieldbook (read-only snapshot)
-```
-
-**A dated line, or it did not happen.** Promised → measured → accepted, with evidence for the measurement. If it is not in `.fde/`, it is not on the record.
-
-**Review judgments before recording them.** The agent shows proposed interpretations for confirmation. Direct CLI writes execute when invoked; enabled session hooks also capture mechanical session state automatically. Recording a note does not establish customer approval.
-
-**The record is on your laptop.** Change hosts and keep the same Markdown. Claude Code plugins provide automatic session hooks; other hosts use `@fde` and CLI commands on demand. See the [install matrix](docs/install.md#who-needs-which-install).
-
-One skill hosts load: `skills/fde/SKILL.md`. It opens one file in `skills/fde/references/` and stops. Slash commands live in `.claude/commands/`. The local CLI is `bin/fde.js` (git + files, no network). Layout: [docs/REPO_LAYOUT.md](docs/REPO_LAYOUT.md).
 
----
+Open a client, inspect its record, and copy an action into your agent to continue the work. The dashboard is a read-only snapshot. After updating the record, run the command again to refresh it. The screenshot uses fictional clients.
 
-## Engagement memory (`.fde/`)
+<a name="how-skills-work"></a>
 
-One folder per client. Plain markdown. Grep it, copy it, take it into a meeting.
+## From the first meeting to handover
 
-| File | Holds |
-|------|-------|
-| `context.md` | Where you are |
-| `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]` - worst active signal wins; empty is **new**, not green |
-| `trust-profile.md` | Sacred data, AI policy, approval chain |
-| `decisions.md` / `risks.md` / `delivery.md` | Dated choices; live risks; what shipped, evidence, rollback, acceptance |
+Describe the situation to `@fde`; it selects the relevant workflow. You do not need to learn a catalog of skills.
 
-Schema: [docs/schema.md](docs/schema.md). Fieldbook: `npx fdeops dashboard --open` (bound) or `--all --open` (portfolio).
+| Stage | What you work through |
+|---|---|
+| Land | Understand the brief and name who can accept the work |
+| Discover | Check the actual workflow, constraints, and source of the problem |
+| Plan | Agree a small deliverable and an observable test for “done” |
+| Ship | Prove it on their staging, review release approval, and test recovery |
+| Outcome | Compare promised and measured results; record customer acceptance |
+| Close | Transfer the runbook, evidence, open risks, and operating ownership |
 
----
+The Claude Code plugin also provides `/brief`, `/discover`, `/plan`, `/ship`, `/outcome`, and `/close`. Daily plugin shortcuts are `/debrief`, `/prep`, `/trust`, `/receipts`, and `/readout`. Other hosts use the same `@fde` entry and methodology.
 
-## Who this is for
+Each skill gives the agent steps to follow, a record to produce, and a checkpoint with you. There are 30 routed skills, plus industry overlays. Start with the [three delivery checklists](docs/skills.md#three-delivery-checklists); use the [full reference](docs/skills-reference.md) when you need the detail.
 
-Forward Deployed Engineers, independent consultants, and solo agencies delivering inside customer systems. Use a separate engagement folder for each client and a workspace binding to select the right record.
+## Use the CLI directly
 
-If you ship your own company's product from HQ, with no customer team that has to run it after you leave, you do not need this kit.
+The CLI does the file work without calling a model. Commands that change records write when you run them; `debrief --smart` stages a proposal for review before `--apply`.
 
----
+| You need to… | Run |
+|---|---|
+| Resume a client | `npx fdeops resume` |
+| Review messy notes | `npx fdeops debrief --smart notes.md` |
+| Apply the reviewed proposal | `npx fdeops debrief --apply` |
+| Find a source | `npx fdeops recall "retry decision"` |
+| Prepare a sponsor readout | `npx fdeops defend` |
+| Check readiness to plan or build | `npx fdeops doctor --ready` |
+| Export a successor packet | `npx fdeops handoff --out successor.md` |
 
-## Your data stays yours
+[All commands and examples](docs/USAGE.md).
 
-The **CLI** is local: git + files, no network, no telemetry. The **host model** sees `.fde/` the agent loads (usually a bounded `context.md`) and any client code you open. It must not see `<private>` blocks - redacted from CLI, dashboard, and hooks; do not paste them or open them with file tools. Keep the engagement folder outside cloud-sync locations unless customer policy permits that storage. Generated reports can still contain confidential information after redaction; review them before sharing.
+For free-form notes, start with `@fde` so your agent can help interpret them. The CLI's `--smart` option recognizes common phrases; review its proposal because it can miss requests or next actions in ordinary prose.
 
-[PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
+## Your records, your control
 
----
+Each client has its own `.fde/` folder of Markdown files. The brief, success criteria, decisions, risks, and delivery ledger stay readable outside FDEOps. The CLI uses local files and Git, with no network calls or telemetry. Optional [MCP sources](mcp/recipes/) are connected through your agent host, then pulled and reviewed on request.
 
-## Principles
+Default session context is capped at **16 KiB**, including constraints and selected records. Older detail stays on disk and can be retrieved with `recall`. This limits FDEOps output, not everything your agent puts into its context window.
 
-- **Who signs** - name them in the first days
-- **Brief vs real job** - check the floor, not only the slide
-- **Back from done** - sequence from signed-off, not from the ticket
-- **Their staging then live** - prove it where they operate, then go live
-- **Promised, measured, accepted** - a number nobody signed is claimed, not delivered; keep the evidence
-- **They run it** - if they cannot operate it without you, you are not done
-- **A dated line, or it did not happen** - these files get defended in the room
-- **One customer, one folder** - verify the active binding before writing
-- **The kit says what to check. You still decide.**
+Your AI host may send what it reads to its configured model. FDEOps redacts `<private>` blocks from its CLI, hook, and dashboard outputs; do not paste or load raw private blocks through file tools. Enabled session hooks can record mechanical session state automatically. Review reports before sharing client information.
 
----
+The CLI and dashboard need no model. The tested small local models produced wrong or incomplete answers; read the results before relying on one for client work. [Verification and limits](docs/verification.md) · [Privacy](PRIVACY.md) · [Security](SECURITY.md).
 
-## Project Structure
+## Find your way around
 
-| Folder | Responsibility |
+| You want to… | Start here |
 |---|---|
-| `skills/fde/` | One router and the delivery methodology |
-| `bin/` | Local CLI, installer, and shared helpers |
-| `templates/.fde/` | Client record templates |
-| `adapters/` and `hooks/` | Host entry points and session integration |
-| `mcp/` | Optional ingest wrapper and source recipes |
-| `test/` and `evals/` | Code regressions and workflow evaluations |
-| `docs/` and `examples/` | Usage, contributor guides, and fictional engagements |
-
-See [repository layout](docs/REPO_LAYOUT.md) for where to make changes.
-
-
----
-
-## Contributing
-
-**[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. [Issues](https://github.com/suboss87/fdeops/issues) · [Discussions](https://github.com/suboss87/fdeops/discussions) · [CONTRIBUTING.md](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md)
+| Install or use FDEOps | [Documentation](docs/README.md) |
+| Understand or change a workflow | [The `@fde` skill](skills/fde/SKILL.md) and its `references/` |
+| Work on the CLI or dashboard | [`bin/`](bin/), shared helpers in `bin/lib/`, regressions in [`test/`](test/) |
+| Explore sample client records | [`examples/`](examples/) |
+| Check measured behavior and known gaps | [`evals/`](evals/) and [verification](docs/verification.md) |
+| Understand every folder | [Repository map](docs/REPO_LAYOUT.md) |
 
-Skills should be **specific** (actionable steps), **verifiable** (an artifact in `.fde/`), and **minimal**. The `fde` CLI stays local-only.
+## Contribute
 
-## License
+Share an anonymized failure case, a reproducible bug, or a focused improvement through [Issues](https://github.com/suboss87/FDEOps/issues) or [Discussions](https://github.com/suboss87/FDEOps/discussions). Read the [contribution guide](CONTRIBUTING.md) before changing a workflow or command.
 
-MIT - use these skills on client work.
+Built and maintained by **[Subash Natarajan](https://github.com/suboss87)**. MIT licensed; preserve applicable notices when redistributing.

package/bin/check.js

@@ -264,39 +264,28 @@ for (const m of readme.matchAll(/(?:\]\(|src=")([^)"#\s]+)(?:\)|")/g)) {
 if (brokenLinks.length) fail(`README links to missing paths: ${brokenLinks.join(', ')}`)
 else ok('README links all resolve')
 
-for (const section of [
-  'How Skills Work',
-  'Quick Start',
-  'Engagement memory',
-  'Who this is for',
-  'Commands',
-  'Principles',
-]) {
-  if (!readme.includes(section)) fail(`README missing section: ${section}`)
+// Validate usable entry points, not a fixed heading order or marketing copy.
+// Host-specific commands and advanced setup belong in the linked guides.
+for (const target of ['docs/install.md', 'docs/USAGE.md', 'docs/REPO_LAYOUT.md', 'docs/verification.md', 'PRIVACY.md']) {
+  if (!readme.includes(target)) fail(`README must link its public guide: ${target}`)
 }
-if (!readme.includes('AI coding agent')) {
-  fail('README must say AI coding agent (not ambiguous "agent")')
+if (!readme.includes('AI coding agent') || !/FDE|Forward Deployed Engineer/i.test(readme)) {
+  fail('README must identify the tool and its intended users')
+}
+if (!/npx skills add suboss87\/fdeops --skill fde/.test(readme) || !/@fde\s+this is/.test(readme)) {
+  fail('README must show skill installation and how to start a client')
 }
-ok('README clarity sections')
-
 for (const cmd of ['/brief', '/discover', '/plan', '/ship', '/outcome', '/close', '/debrief', '/prep', '/trust', '/receipts', '/readout']) {
-  if (!readme.includes(cmd)) fail(`README must document slash command ${cmd}`)
+  if (!(readme + usage).includes(cmd)) fail(`Public usage documentation missing slash command ${cmd}`)
 }
 if (/(^|[^\w/])\/got\b/.test(readme)) fail('README must use /outcome, not /got')
-ok('README slash commands documented')
-
-// Front-door map is the embed left-to-right (Land → Close). After the GitHub
-// poster (#68) the table is the map: /brief /discover /plan /ship /outcome /close.
-const front = readme.slice(0, 4000)
-if (!['/brief', '/discover', '/plan', '/ship', '/outcome', '/close'].every(c => front.includes(c))) {
-  fail('README must include the Land→Close command map near the top')
-} else ok('README command-map diagram')
+ok('README entry points and documented commands')
 
 if (readme.includes('your-client-repo')) {
   fail('README must not instruct install in customer repo (your-client-repo)')
 } else ok('README no customer-repo install')
 
-if (!readme.includes('fde-engagements') || !/fdeops.*init.*engagement/i.test(readme)) {
+if (!readme.includes('fde-engagements') || !/fdeops.*resume --init/i.test(readme + read('docs/install.md'))) {
   fail('README must document fde-engagements + init flow')
 } else ok('README engagement path')
 
@@ -334,9 +323,9 @@ if (!fs.existsSync(path.join(root, 'docs', 'USAGE.md'))) {
   fail('docs/USAGE.md missing')
 } else ok('docs/USAGE.md')
 
-if (!readme.includes('FDEOPS_ENGAGEMENT')) {
-  fail('README must document FDEOPS_ENGAGEMENT')
-} else ok('README FDEOPS_ENGAGEMENT')
+if (!read('docs/install.md').includes('FDEOPS_ENGAGEMENT')) {
+  fail('Installation guide must document FDEOPS_ENGAGEMENT')
+} else ok('Installation override documented')
 
 const badPhrases = ['team of ten', 'solo 100x', '100x engineer']
 for (const phrase of badPhrases) {
@@ -356,12 +345,6 @@ for (const rx of derivativeFraming) {
 if (/docs\/internal|PMF_360/i.test(readme)) {
   fail('README must not link docs/internal or PMF_360')
 }
-if (!/One command per stage/.test(readme) || !/Skills load automatically/.test(readme)) {
-  fail('README must formulate Commands as: one command per stage, skills load automatically')
-}
-if (!/Not prompts/.test(readme)) {
-  fail('README catalog must say skills are not prompts')
-}
 if (/\b(30|31|37)\s+methods\b|\broutes methods\b|\bphase methods\b|\bfield methods\b|\bengagement methods\b/.test(readme)) {
   fail('README must call the catalog skills, not methods')
 }