fdeops 3.27.0 → 3.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +216 -78
  2. package/bin/check.js +15 -32
  3. package/bin/fde.js +268 -51
  4. package/bin/lib/render.js +2 -2
  5. package/bin/lib/trust.js +4 -28
  6. package/bin/lib/value-ledger.js +46 -1
  7. package/mcp/fdeops-ingest/package.json +1 -1
  8. package/package.json +1 -1
  9. package/plugin.json +1 -1
  10. package/skills/fde/references/audit.md +3 -3
  11. package/skills/fde/references/debrief.md +13 -1
package/README.md CHANGED
@@ -1,158 +1,296 @@
1
1
  # FDEOps
2
2
 
3
- **The local engagement OS for AI coding agents.**
3
+ **Forward deployed engineering skills for AI coding agents.**
4
4
 
5
- FDEOps helps a Forward Deployed Engineer or consultant carry a client engagement from a messy brief to a defensible handover. One `@fde` entry guides the work. A local CLI keeps the record in Markdown; an offline fieldbook shows what needs attention.
5
+ <a name="why-use-it"></a>
6
6
 
7
- | When client work goes wrong | What FDEOps helps you keep straight |
8
- |---|---|
9
- | The brief describes the wrong problem | What was requested, what you observed, and which assumptions remain untested |
10
- | Nobody can say who signs | The acceptance owner, approval scope, and unresolved authority |
11
- | A good number becomes a success claim | What was promised, measured, and accepted, with its source |
12
- | You switch clients, agents, or engineers | Decisions, constraints, evidence, and one next action in each client's record |
7
+ You're on a customer site. The AI coding agent writes code in their repo. This kit is the work around that code: the brief, who can say yes, proof on their staging then live, whether they signed off, whether they can run it after you leave.
8
+
9
+ Notes stay on your laptop, in a separate record for each client. Review the agent's proposed changes before saving them.
10
+
11
+ Keep the coding pack you already use. FDEOps adds the client brief, decisions, and evidence around that work.
13
12
 
14
- You make the judgments and obtain customer approval. The record helps you explain them later.
13
+ [Quick start](#quick-start) · [Daily fieldbook](#your-daily-fieldbook) · [30 skills](#all-30-skills) · [Documentation](docs/README.md)
15
14
 
16
- <img width="1536" height="1024" alt="fdeops" src="https://github.com/user-attachments/assets/2bcb8739-55ee-445d-8a1a-8b38433b7b58" />
15
+ <img width="960" height="640" alt="FDEOps: client delivery from the first meeting to handover" src="https://github.com/user-attachments/assets/2bcb8739-55ee-445d-8a1a-8b38433b7b58" />
16
+
17
+ ---
17
18
 
18
19
  ## Quick Start
19
20
 
20
- Requires Node.js 18+, Git, and an AI coding agent for the guided workflow. `npx` may download packages; the FDEOps CLI operates locally.
21
+ **Try it in a local checkout.** Requires Node.js 18+ and Git:
22
+
23
+ ```bash
24
+ npx fdeops scan
25
+ ```
26
+
27
+ It prints what to look at on day one and the questions to ask. The scan reads local files without changing them. `npx` may download the package.
28
+
29
+ **Then install the skill:**
21
30
 
22
31
  ```bash
23
32
  npx skills add suboss87/fdeops --skill fde
24
33
  ```
25
34
 
26
- Open the client workspace and tell your agent:
35
+ One chat. Name the client:
27
36
 
28
37
  ```text
29
38
  @fde this is client01
30
39
  ```
31
40
 
32
- The agent creates `~/fde-engagements/client01/.fde/` and binds the workspace to it. If the host cannot run setup, use `npx fdeops resume --init client01` to create the engagement and binding.
41
+ That creates `~/fde-engagements/client01/.fde/` on your laptop. Paste kickoff notes in the same thread. `@fde` picks what to check. You still decide. After a meeting you review what changed, new asks, open questions, and next actions. Correct the proposal, then confirm the update.
33
42
 
34
- **Try the record before using client data:** `npx fdeops demo` runs a fictional notes-to-fieldbook workflow without a model. It writes under `~/fde-engagements/.demo/` and resets that sandbox each run. Remove it with `npx fdeops demo --clean`. For repository reconnaissance without writing engagement records, use `npx fdeops scan`.
43
+ Open the engagement fieldbook:
35
44
 
36
- <details>
37
- <summary>Host installation and offline use</summary>
45
+ ```bash
46
+ npx fdeops dashboard --open
47
+ ```
38
48
 
39
- Claude Code plugin:
49
+ 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).
50
+
51
+ <details>
52
+ <summary><b>Claude Code</b></summary>
40
53
 
41
54
  ```text
42
55
  /plugin marketplace add suboss87/fdeops
43
56
  /plugin install fdeops@fdeops
44
57
  ```
45
58
 
46
- The plugin registers session hooks and slash commands. Skill-only installations do not register those hooks. For Cursor, Codex, Gemini, or Copilot, install the skill and run `npx fdeops adapters .` in the client workspace; this writes instruction pointers.
59
+ The plugin adds session hooks and the slash commands below. Skill-only installation does not add hooks. See the [installation guide](docs/install.md) for setup details.
60
+
61
+ </details>
62
+
63
+ <details>
64
+ <summary><b>Cursor</b></summary>
47
65
 
48
- Clone installation:
66
+ After installing the skill, add the FDEOps instructions to the **client workspace** you have open:
49
67
 
50
68
  ```bash
51
- git clone https://github.com/suboss87/fdeops.git
52
- cd fdeops
53
- node bin/install.js
69
+ npx fdeops adapters .
54
70
  ```
55
71
 
56
- Offline machines need an already-transferred checkout, Node.js, and Git. Advanced override: `FDEOPS_ENGAGEMENT`. See [installation](docs/install.md) and [host adapters](adapters/README.md).
72
+ See [adapters/](adapters/README.md).
57
73
 
58
74
  </details>
59
75
 
60
- ## Commands
61
-
62
- One command per stage. Skills load automatically. Describe the situation to `@fde`; the Claude Code plugin also provides these slash commands.
63
-
64
- | Stage | Command | Result to review |
65
- |---|---|---|
66
- | Land | `/brief` | The brief, unknowns, and who can accept the work |
67
- | Discover | `/discover` | The actual workflow and evidence behind the problem |
68
- | Plan | `/plan` | A small deliverable, constraints, and acceptance criteria |
69
- | Ship | `/ship` | Proof on their staging, release approval, and rollback |
70
- | Outcome | `/outcome` | Promised, measured, accepted, and supporting evidence |
71
- | Close | `/close` | Runbook, operating owner, and handover gaps |
76
+ <details>
77
+ <summary><b>Codex, other agents, and offline setup</b></summary>
72
78
 
73
- Daily requests: `/debrief`, `/prep`, `/receipts`, `/readout`, and `/trust`. Revisit earlier stages when evidence changes; a new incident does not require restarting discovery.
79
+ Use the skill installation above in a supported host. If the agent cannot create and bind the client folder, run this from the client workspace:
74
80
 
75
- ## One loop you can defend
81
+ ```bash
82
+ npx fdeops resume --init client01
83
+ ```
76
84
 
77
- Paste messy notes after a meeting:
85
+ For offline use, transfer an existing checkout to a machine with Node.js and Git, then run `node bin/install.js` from that checkout. Host adapters, local models, and advanced options are covered in [docs/install.md](docs/install.md).
78
86
 
79
- ```text
80
- @fde Debrief: Mara agreed to CSV upload. Devon asked for ERP sync,
81
- but Mara has not approved it. The staging replay took 5 minutes;
82
- we have no comparable production baseline. Ask Mara for staging access.
83
- ```
87
+ </details>
84
88
 
85
- 1. **Review:** the agent separates decisions, requests, unknowns, measurements, and next actions. Check the source and any conflicts with existing records.
86
- 2. **Apply:** confirm the proposed interpretation. An ERP request stays a request; a staging result stays a staging result. Saving the record does not mean the customer approved either.
87
- 3. **Defend:** ask `@fde What did we agree about ERP, and what evidence supports the result?` Review the supplied source, superseded decisions, and missing evidence before using the answer in a sponsor update.
88
89
 
89
- The CLI supports this loop with `debrief --smart`, reviewed `--apply`, `recall`, `receipts`, and `defend`. `fde handoff --out successor.md` creates a new portable, redacted packet. See the [walkthrough](docs/USAGE.md) for examples. Direct CLI write commands execute when invoked; enabled session hooks automatically capture mechanical session state. Agent judgments still need review.
90
+ <a name="what-a-working-day-looks-like"></a>
90
91
 
91
92
  ## Your daily fieldbook
92
93
 
93
- ![FDEOps dark dashboard showing next actions and attention gaps across three fictional clients](media/fieldbook-preview.png)
94
+ See what needs your attention before you open another client thread: an open risk, missing evidence, a result waiting for acceptance, or the next action.
94
95
 
95
- *Fictional client records in the built-in dark theme. The report works offline.*
96
+ ![Dark FDEOps fieldbook showing next actions and delivery gaps across fictional clients](media/fieldbook-preview.png)
96
97
 
97
98
  ```bash
98
- npx fdeops dashboard --open # this client
99
- npx fdeops dashboard --all --open # all clients
99
+ npx fdeops dashboard --all --open
100
100
  ```
101
101
 
102
- Filter what needs attention, open a client, and copy **Continue next action**, **Debrief notes**, or **Review outcome** into your agent. The fieldbook is a read-only snapshot: work happens in your agent or CLI, then you regenerate the report. Review confidential information before sharing it with a sponsor or incoming engineer.
102
+ Open a client, inspect its record, and copy an action into your agent to continue. The dashboard is a read-only snapshot; repeat the command after updating your records to refresh it.
103
+
104
+ **Want to see the whole loop first?** `npx fdeops demo` runs fictional notes through review and prints a sample fieldbook path to open. It writes and resets its own folder under `~/fde-engagements/.demo/`, needs no AI model, and can be removed with `npx fdeops demo --clean`.
105
+
106
+ ⭐ If FDEOps makes your client work easier, star the repo.
107
+
108
+ ---
109
+
110
+ <a name="from-the-first-meeting-to-handover"></a>
111
+
112
+ ## Commands
113
+
114
+ Describe the situation to `@fde`. It selects the relevant skill. The Claude Code plugin also provides these stage commands; other hosts use the same method through `@fde`.
115
+
116
+ | What you're doing | Command | Stage |
117
+ |-------------------|---------|-------|
118
+ | First days. Get the brief. Name who signs. | `/brief` | Land |
119
+ | Check the brief is the real job. | `/discover` | Discover |
120
+ | Sequence from done, not from the ticket. | `/plan` | Plan |
121
+ | Prove it on their staging, then go live. | `/ship` | Ship |
122
+ | What you promised, measured, and who accepted. | `/outcome` | Outcome |
123
+ | Hand it over. They run it without you. | `/close` | Close |
124
+
125
+ Claude Code shortcuts for the moments between stages: `/debrief` (notes into the record), `/prep` (one page before you walk in), `/trust` (process gap, or they stopped trusting you), `/receipts` (find what was recorded and where it came from), `/readout` (Friday page for the sponsor; not a seventh stage).
126
+
127
+ You can also just say it: “Prep me for the sponsor meeting,” “What did we agree about scope?” or “Help me hand this over.”
128
+
129
+ ---
130
+
131
+ ## All 30 Skills
132
+
133
+ Thirty situations, grouped by stage. Each skill gives the agent steps to follow, a record or report to produce, and a checkpoint with you. You describe the work; `@fde` finds the skill.
134
+
135
+ Full detail: [docs/skills-reference.md](docs/skills-reference.md).
136
+
137
+ ### Land
138
+
139
+ | Skill | What it does | Use when |
140
+ |--------|--------------|----------|
141
+ | [land](skills/fde/references/land.md) | Interrogate the brief | New client, first meeting, just got the brief |
142
+ | [audit](skills/fde/references/audit.md) | Verify inherited claims | Taking over, previous consultant left |
143
+ | [who-decides](skills/fde/references/who-decides.md) | Map decision rights | Need to know who matters |
144
+ | [earn-trust](skills/fde/references/earn-trust.md) | Earn access | Need access or credibility |
145
+ | [hold-scope](skills/fde/references/hold-scope.md) | Hold scope | "Also can you…", timeline unchanged |
146
+
147
+ ### Discover
148
+
149
+ | Skill | What it does | Use when |
150
+ |--------|--------------|----------|
151
+ | [discover](skills/fde/references/discover.md) | Frame the problem | Brief feels wrong, shadow processes |
152
+ | [test-assumptions](skills/fde/references/test-assumptions.md) | Test assumptions | Brief feels too neat |
153
+ | [score-use-cases](skills/fde/references/score-use-cases.md) | Score use cases | Everything is P0 |
154
+ | [poc](skills/fde/references/poc.md) | Validate the solution | POC, spike, need to de-risk |
155
+
156
+ ### Plan
157
+
158
+ | Skill | What it does | Use when |
159
+ |--------|--------------|----------|
160
+ | [plan](skills/fde/references/plan.md) | Sequence the work | What order, what is done |
161
+ | [business-case](skills/fde/references/business-case.md) | Build the business case | Defend budget or timeline |
162
+ | [three-options](skills/fde/references/three-options.md) | Generate options | "What should we do?" |
163
+ | [pick-three](skills/fde/references/pick-three.md) | Prioritize three | Everything is urgent |
164
+
165
+ ### Ship
166
+
167
+ | Skill | What it does | Use when |
168
+ |--------|--------------|----------|
169
+ | [ship](skills/fde/references/ship.md) | Deliver the increment | Building, updating, or going live |
170
+ | [what-breaks](skills/fde/references/what-breaks.md) | Assess impact | Touching shared infrastructure |
171
+ | [rescue](skills/fde/references/rescue.md) | Resolve the incident | Down, or they went quiet |
172
+ | [review](skills/fde/references/review.md) | Review the change | Before merge, scope creep |
173
+ | [rollback](skills/fde/references/rollback.md) | Rehearse rollback | "We can always revert" |
174
+
175
+ ### Outcome
176
+
177
+ | Skill | What it does | Use when |
178
+ |--------|--------------|----------|
179
+ | [readout](skills/fde/references/readout.md) | Report the outcome | Friday, sponsor update |
180
+ | [demo-prep](skills/fde/references/demo-prep.md) | Prepare the demo | Demo or exec walkthrough |
181
+ | [debrief](skills/fde/references/debrief.md) | Capture the meeting | Just left a meeting |
182
+ | [board-memo](skills/fde/references/board-memo.md) | Brief the board | Justify continued investment |
183
+ | [dashboard](skills/fde/references/dashboard.md) | Open the fieldbook | This customer, or all of them |
184
+ | [ingest](skills/fde/references/ingest.md) | Ingest sources | Transcript, Notion, Slack |
185
+ | [connect](skills/fde/references/connect.md) | Connect a source | Connect Granola |
186
+
187
+ ### Close
188
+
189
+ | Skill | What it does | Use when |
190
+ |--------|--------------|----------|
191
+ | [close](skills/fde/references/close.md) | Transfer operations | Wrapping up |
192
+ | [runbook](skills/fde/references/runbook.md) | Write the runbook | They must operate without you |
193
+ | [switch-clients](skills/fde/references/switch-clients.md) | Switch engagements | 2+ clients |
194
+ | [encode-pattern](skills/fde/references/encode-pattern.md) | Encode the pattern | It will apply again |
195
+ | [red-team](skills/fde/references/red-team.md) | Challenge the plan | "Poke holes in this" |
196
+
197
+ Overlays (on signal, not on request): [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). AI companion (not a sixth overlay): [eval-pack](skills/fde/references/eval-pack.md).
198
+
199
+ Optional pull: you add the source MCP; we **pull** on request. [mcp/recipes/](mcp/recipes/)
200
+
201
+ ---
202
+
203
+ <a name="use-the-cli-directly"></a>
103
204
 
104
205
  ## How Skills Work
105
206
 
106
- One entry, one source of methodology, one record per client:
207
+ One `@fde`. One file per situation. One folder per client.
107
208
 
108
- ```text
109
- @fde + your situation → one relevant skill → reviewed work → .fde/ → fieldbook
110
- ```
209
+ Tell the agent what is happening. It reads the client record, opens the relevant skill, and works through the situation with you. After a meeting, it proposes the decisions, open questions, and next action. You correct what it misunderstood and confirm the update.
111
210
 
112
- **All 30 skills:** Not prompts to choose from. Each reference contains steps, an artifact, and a checkpoint. The [skills guide](docs/skills.md) has three short checklists for day zero, discovery to a small ship, and POC to production. The [full reference](docs/skills-reference.md) covers all stages and overlays.
211
+ A request stays a request until agreed. A staging result stays separate from production. Recording a result does not mean the customer accepted it.
113
212
 
114
- Optional external sources use MCP connections configured in your agent host. Pull material on request, review its interpretation, then apply it. The CLI does not connect to those services. See [source recipes](mcp/recipes/).
213
+ At the next session, FDEOps supplies a short summary instead of the whole history. Older detail stays on disk; `recall` finds relevant records when needed. The default summary is capped at 16 KiB, which limits FDEOps output rather than everything your agent loads.
214
+
215
+ Before a sponsor meeting, `npx fdeops defend` separates recorded acceptance from claims and missing evidence. For a successor, `npx fdeops handoff --out successor.md` creates a portable summary with risks and sources.
216
+
217
+ For free-form notes, start with `@fde`. The CLI's `debrief --smart` recognizes common phrases; it can miss details that your agent needs to help interpret. [Follow the notes → review → apply walkthrough](docs/USAGE.md#new-here-5-minutes).
218
+
219
+ ---
115
220
 
116
221
  ## Engagement memory (`.fde/`)
117
222
 
118
- | Record | What it preserves |
119
- |---|---|
120
- | `context.md` | Current state and next action |
121
- | `brief.md`, `reality.md`, `terrain.md` | Request, observed problem, and system constraints |
122
- | `success.md`, `stakeholders.md`, `trust-profile.md` | Acceptance criteria, people, data policy, and authority |
123
- | `decisions.md`, `risks.md`, `delivery.md` | Choices, unresolved risks, measurements, evidence, and recorded acceptance |
223
+ One folder per client. Plain markdown. Grep it, copy it, take it into a meeting.
224
+
225
+ | File | Holds |
226
+ |------|-------|
227
+ | `context.md` | Where you are |
228
+ | `brief.md` / `success.md` | What they asked; what “done” is and who signs |
229
+ | `reality.md` / `terrain.md` | The real problem; the map |
230
+ | `stakeholders.md` | `[signal:green\|amber\|red]` - worst active signal wins; empty is **new**, not green |
231
+ | `trust-profile.md` | Sacred data, AI policy, approval chain |
232
+ | `decisions.md` / `risks.md` / `delivery.md` | Dated choices; live risks; what shipped, evidence, rollback, acceptance |
124
233
 
125
- Markdown stays on your machine when you change hosts. Bounded `resume` and topic-based `recall` reduce what enters the active context; omitted history still needs retrieval. See the [record schema](docs/schema.md) and [verification results](docs/verification.md). Passing software tests does not establish reliable judgment from every model.
234
+ Schema: [docs/schema.md](docs/schema.md). Fieldbook: `npx fdeops dashboard --open` (bound) or `--all --open` (portfolio).
235
+
236
+ ---
126
237
 
127
238
  ## Who this is for
128
239
 
129
- FDEs, independent consultants, and solo agencies working inside customer systems. Sponsors and incoming engineers can review the resulting records and reports without learning the skill catalog. FDEOps supports delivery decisions; it does not replace customer authority or operate their infrastructure for you.
240
+ Forward deployed engineers, independent consultants, and small agencies working with customer teams. You need to carry the brief, decisions, delivery evidence, and handover across meetings, repositories, and sometimes several clients.
130
241
 
131
- ## Principles
242
+ If your work has no client commitments or operating handover to track, a simpler project note may be enough.
132
243
 
133
- - Verify the brief before building; keep unknowns explicit.
134
- - Name who can accept which outcome.
135
- - Keep promised, measured, and accepted results separate.
136
- - Prove a small change where the client will operate it, with a tested recovery path.
137
- - Leave a record another engineer can understand and challenge.
138
- - Keep each client separate and confirm the active binding before writing.
244
+ <a name="your-records-your-control"></a>
139
245
 
140
246
  ## Your data stays yours
141
247
 
142
- The CLI uses local files and Git, with no network or telemetry. Your AI host may send the material it reads to its configured model. CLI, hook, and fieldbook outputs redact `<private>` blocks; do not paste or load raw private blocks with file tools. Follow customer storage policy and review reports before sharing.
248
+ The CLI works with local files and Git, without network calls or telemetry. Client records remain readable Markdown if you stop using FDEOps.
249
+
250
+ Your AI host may send the material it reads to its configured model. FDEOps redacts `<private>` blocks from CLI, dashboard, and hook outputs; do not load those raw blocks through the agent's file tools. Review reports before sharing client information.
251
+
252
+ You review proposed decisions. Enabled session hooks can save where the session left off automatically; direct CLI write commands update records when you run them.
253
+
254
+ The CLI and dashboard need no model. AI-assisted local use needs an agent with file and command access. Our small local-model tests produced wrong or incomplete answers, so check the [verification results](docs/verification.md) before relying on one for client work.
143
255
 
144
256
  [Privacy](PRIVACY.md) · [Security](SECURITY.md)
145
257
 
258
+ ## Principles
259
+
260
+ - **Who signs** - name who can accept the work.
261
+ - **Brief vs real job** - check what happens on the floor, not only the slide.
262
+ - **Back from done** - agree how you will test success before planning the build.
263
+ - **Their staging, then live** - prove the change and agree the release and rollback.
264
+ - **Promised, measured, accepted** - keep each separate, with its evidence.
265
+ - **They run it** - hand over the knowledge and ownership, not just the code.
266
+ - **The kit says what to check. You still decide.**
267
+
268
+ ---
269
+
270
+ <a name="find-your-way-around"></a>
271
+
146
272
  ## Project Structure
147
273
 
148
- Methodology lives in `skills/fde/`; deterministic commands and shared helpers in `bin/`; host entry points in `adapters/` and `hooks/`. `templates/`, `test/`, `evals/`, and `examples/` support the same workflow. The [repository map and documentation index](docs/REPO_LAYOUT.md) explain where to start and where changes belong.
274
+ | You want to… | Start here |
275
+ |---|---|
276
+ | Install or use FDEOps | [docs/](docs/README.md) |
277
+ | Understand or change a workflow | [skills/fde/](skills/fde/SKILL.md) and its `references/` |
278
+ | Work on the CLI or fieldbook | [bin/](bin/) and [test/](test/) |
279
+ | Walk through a client engagement | [examples/](examples/) |
280
+ | Check what has been tested | [evals/](evals/) and [verification](docs/verification.md) |
281
+
282
+ [Full repository map](docs/REPO_LAYOUT.md).
283
+
284
+ ---
285
+
286
+ <a name="contribute"></a>
149
287
 
150
288
  ## Contributing
151
289
 
152
- Maintained by **[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. 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).
290
+ **[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)
153
291
 
154
- [Contribution guide](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md)
292
+ Skills should be **specific** (actionable steps), **verifiable** (an artifact in `.fde/`), and **minimal**. The `fde` CLI stays local-only.
155
293
 
156
294
  ## License
157
295
 
158
- MIT - use FDEOps on client work. Preserve applicable license notices when redistributing.
296
+ MIT - use these skills on client work.
package/bin/check.js CHANGED
@@ -264,39 +264,28 @@ for (const m of readme.matchAll(/(?:\]\(|src=")([^)"#\s]+)(?:\)|")/g)) {
264
264
  if (brokenLinks.length) fail(`README links to missing paths: ${brokenLinks.join(', ')}`)
265
265
  else ok('README links all resolve')
266
266
 
267
- for (const section of [
268
- 'How Skills Work',
269
- 'Quick Start',
270
- 'Engagement memory',
271
- 'Who this is for',
272
- 'Commands',
273
- 'Principles',
274
- ]) {
275
- if (!readme.includes(section)) fail(`README missing section: ${section}`)
267
+ // Validate usable entry points, not a fixed heading order or marketing copy.
268
+ // Host-specific commands and advanced setup belong in the linked guides.
269
+ for (const target of ['docs/install.md', 'docs/USAGE.md', 'docs/REPO_LAYOUT.md', 'docs/verification.md', 'PRIVACY.md']) {
270
+ if (!readme.includes(target)) fail(`README must link its public guide: ${target}`)
276
271
  }
277
- if (!readme.includes('AI coding agent')) {
278
- fail('README must say AI coding agent (not ambiguous "agent")')
272
+ if (!readme.includes('AI coding agent') || !/FDE|Forward Deployed Engineer/i.test(readme)) {
273
+ fail('README must identify the tool and its intended users')
274
+ }
275
+ if (!/npx skills add suboss87\/fdeops --skill fde/.test(readme) || !/@fde\s+this is/.test(readme)) {
276
+ fail('README must show skill installation and how to start a client')
279
277
  }
280
- ok('README clarity sections')
281
-
282
278
  for (const cmd of ['/brief', '/discover', '/plan', '/ship', '/outcome', '/close', '/debrief', '/prep', '/trust', '/receipts', '/readout']) {
283
- if (!readme.includes(cmd)) fail(`README must document slash command ${cmd}`)
279
+ if (!(readme + usage).includes(cmd)) fail(`Public usage documentation missing slash command ${cmd}`)
284
280
  }
285
281
  if (/(^|[^\w/])\/got\b/.test(readme)) fail('README must use /outcome, not /got')
286
- ok('README slash commands documented')
287
-
288
- // Front-door map is the embed left-to-right (Land → Close). After the GitHub
289
- // poster (#68) the table is the map: /brief /discover /plan /ship /outcome /close.
290
- const front = readme.slice(0, 4000)
291
- if (!['/brief', '/discover', '/plan', '/ship', '/outcome', '/close'].every(c => front.includes(c))) {
292
- fail('README must include the Land→Close command map near the top')
293
- } else ok('README command-map diagram')
282
+ ok('README entry points and documented commands')
294
283
 
295
284
  if (readme.includes('your-client-repo')) {
296
285
  fail('README must not instruct install in customer repo (your-client-repo)')
297
286
  } else ok('README no customer-repo install')
298
287
 
299
- if (!readme.includes('fde-engagements') || !/fdeops.*init.*engagement/i.test(readme)) {
288
+ if (!readme.includes('fde-engagements') || !/fdeops.*resume --init/i.test(readme + read('docs/install.md'))) {
300
289
  fail('README must document fde-engagements + init flow')
301
290
  } else ok('README engagement path')
302
291
 
@@ -334,9 +323,9 @@ if (!fs.existsSync(path.join(root, 'docs', 'USAGE.md'))) {
334
323
  fail('docs/USAGE.md missing')
335
324
  } else ok('docs/USAGE.md')
336
325
 
337
- if (!readme.includes('FDEOPS_ENGAGEMENT')) {
338
- fail('README must document FDEOPS_ENGAGEMENT')
339
- } else ok('README FDEOPS_ENGAGEMENT')
326
+ if (!read('docs/install.md').includes('FDEOPS_ENGAGEMENT')) {
327
+ fail('Installation guide must document FDEOPS_ENGAGEMENT')
328
+ } else ok('Installation override documented')
340
329
 
341
330
  const badPhrases = ['team of ten', 'solo 100x', '100x engineer']
342
331
  for (const phrase of badPhrases) {
@@ -356,12 +345,6 @@ for (const rx of derivativeFraming) {
356
345
  if (/docs\/internal|PMF_360/i.test(readme)) {
357
346
  fail('README must not link docs/internal or PMF_360')
358
347
  }
359
- if (!/One command per stage/.test(readme) || !/Skills load automatically/.test(readme)) {
360
- fail('README must formulate Commands as: one command per stage, skills load automatically')
361
- }
362
- if (!/Not prompts/.test(readme)) {
363
- fail('README catalog must say skills are not prompts')
364
- }
365
348
  if (/\b(30|31|37)\s+methods\b|\broutes methods\b|\bphase methods\b|\bfield methods\b|\bengagement methods\b/.test(readme)) {
366
349
  fail('README must call the catalog skills, not methods')
367
350
  }