fdeops 4.1.1 → 5.1.0

package/AGENTS.md

@@ -1,10 +1,10 @@
 # AGENTS.md - working in the fdeops repository
 
-This repository **is** fdeops - the engagement record for Forward Deployed Engineers. One `@fde` skill, the `fde` CLI for deterministic work, and per-customer memory in `.fde/` as a side effect of the work (you still confirm judgment).
+This repository **is** FDEOps: skills for Forward Deployed Engineers. The `fde` coordinator selects the relevant instructions for customer work. All 35 task skills also work individually. The local CLI manages customer records in `.fde/` files; users confirm consequential judgments.
 
 ## If you are helping use fdeops in an engagement
 
-Route via **`@fde`** - read `skills/fde/SKILL.md` (the single source of truth), route to one `references/*.md`, do the work, and write `.fde/` memory. Never ask the human to pick a skill. Other tools get the same behavior through thin pointer files in [`adapters/`](adapters/README.md).
+For ongoing customer work, use **`@fde`**: read `skills/fde/SKILL.md`, select the relevant instructions, and follow its record rules. When the user selects a task such as `discover` or `build`, run that task directly with the supplied context; a customer record is optional. Do not make users choose a task when they have asked the coordinator for help. Other tools use thin pointer files in [`adapters/`](adapters/README.md).
 
 ## If you are contributing to this repository
 

package/README.md

@@ -1,333 +1,172 @@
 # FDEOps
 
-**Forward deployed engineering skills for AI coding agents.**
+**Forward deployed engineering skills for your AI coding agent.**
 
 <a name="why-use-it"></a>
 
-Take a customer request from discovery through implementation, verification and handoff. Use one task skill for the work in front of you, or `@fde` to coordinate the engagement and keep its decisions and evidence together.
+Work through a customer project from the first conversation to a system their team can run. FDEOps helps your agent clarify the problem, compare solutions, write and test code, connect customer systems, and prepare delivery and handover evidence.
 
-Notes stay on your laptop, in a separate record for each client. Review the agent's proposed changes before saving them.
+A **skill** is a set of instructions your AI coding agent follows. FDEOps includes **35 task skills + one coordinator, `fde`**. Use any skill directly, or ask `fde` to select the relevant skills as a customer project progresses.
 
-Implementation, integration, debugging and QA are included. Use your existing repository tools; no additional skill pack is required. Credentials, infrastructure and production authority still come from the customer.
+Use it for a single integration, a small client project, or work within a larger enterprise team. You bring the customer context, repository tools and access. FDEOps supplies the working method; you and the responsible teams make the decisions.
 
-[Quick start](#quick-start) · [Daily fieldbook](#your-daily-fieldbook) · [Task skills](#task-skills) · [Documentation](docs/README.md)
+[Get started](#quick-start) · [Choose a task](#task-skills) · [Keep a customer record](#keep-a-customer-record) · [Documentation](docs/README.md)
 
-<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" />
+## Quick start
 
----
+You need an AI coding agent that supports skills. The installation commands and FDEOps CLI require **Node.js 18+ and Git** on your machine.
 
-## Task skills
+### Work on a customer project
 
-Call the task directly when you know what you need. No client folder is required for a one-off task.
-
-| Work | Skill |
-|------|-------|
-| Understand the workflow | `fde-discover` |
-| Handle a new scope request | `fde-scope` |
-| Compare approaches | `fde-options` |
-| Test a risky assumption | `fde-poc` |
-| Implement, integrate, repair | `fde-build`, `fde-integrate`, `fde-debug` |
-| Review, evaluate AI, test the journey | `fde-review`, `fde-evaluate`, `fde-qa` |
-| Release a verified increment | `fde-ship` |
-| Present evidence, transfer operation, reuse a lesson | `fde-readout`, `fde-handoff`, `fde-feedback` |
-
-For example, install just the integration skill:
+Run this in your terminal and select your agent in the installer:
 
 ```bash
-npx skills add suboss87/fdeops --skill fde-integrate
+npx skills add suboss87/fdeops --skill fde
 ```
 
-Ask it to connect a permitted customer API and test retry behavior. It includes the references it needs. `@fde` uses those same methods when the integration is part of an ongoing engagement. [Full pack and selective installation](docs/install.md#individual-skills-and-the-full-pack).
+Then start a conversation with your agent:
 
-## Quick Start
+```text
+@fde this is client01. Their support team reads incoming requests,
+checks internal documents, then assigns each request to another team.
+Help me prepare for the first meeting. Here is the brief: …
+```
 
-**Try it in a local checkout.** Requires Node.js 18+ and Git:
+`fde` asks for the information needed next and uses the relevant instructions. As work progresses, it can help you investigate delays, compare approaches, implement a change, test it, and prepare a customer update. You do not have to choose a skill at each step.
 
-```bash
-npx fdeops scan
-```
+Naming the customer starts a local project record at `~/fde-engagements/client01/.fde/`. It keeps the brief, decisions, evidence and next actions together. Review proposed agreements and corrections before saving them. [How customer records work](#keep-a-customer-record).
 
-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.
+### Use just one task
 
-**Then install the skill:**
+For example, install only `discover`:
 
 ```bash
-npx skills add suboss87/fdeops --skill fde
+npx skills add suboss87/fdeops --skill discover
 ```
 
-One chat. Name the client:
+Then ask your agent:
 
 ```text
-@fde this is client01
+Use FDEOps discover with these meeting notes. Show how the team handles
+an incoming request today, where time goes, and what we still need to ask.
+[Paste notes you are permitted to share.]
 ```
 
-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.
-
-### Make it fit your work
+The agent works from your notes and returns its findings. You do not need to create a customer record for this task. Each task skill includes the instructions it needs and works without installing `fde` or another skill pack.
 
-Setup asks three short questions: how you work, what would help first, and what to mask before sharing context with your agent. Review your choices before saving; change them anytime.
+**Want every task available by name?** Install the full pack using the [installation guide](docs/install.md#individual-skills-and-the-full-pack). Installing `fde` alone gives the coordinator all the underlying instructions; it does not add the 35 separate names to your agent's skill menu.
 
-```bash
-npx fdeops@latest setup
-```
-
-[See the choices and custom masking options](docs/USAGE.md#make-fdeops-fit-your-day).
+Skill invocation differs between agents. Ask for the FDEOps skill by name or select it in your agent's skill picker. For Claude Code plugin installs, use `/fdeops:fde` or `/fdeops:discover`. See [host setup and name conflicts](docs/install.md#individual-skills-and-the-full-pack).
 
-Open the engagement fieldbook:
+## Choose a skill
 
-```bash
-npx fdeops dashboard --open
-```
+<a name="task-skills"></a>
 
-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).
+Use the skill that matches the work in front of you. All skills are individually installable; the [complete catalog](docs/skills-reference.md) lists the input and result for each one.
 
-<details>
-<summary><b>Claude Code</b></summary>
+| You need to… | Start with |
+|---|---|
+| Clarify a new customer request | `brief` or `discover` |
+| Understand who can approve the change | `who-decides` |
+| Decide what to build and what to leave out | `options`, `scope` or `plan` |
+| Implement or connect customer systems | `build` or `integrate` |
+| Find a failure or test the result | `debug`, `review`, `evaluate` or `qa` |
+| Prepare an authorized release | `ship` |
+| Review meeting notes or report progress | `debrief` or `readout` |
+| Prepare the team to run the system | `runbook` or `handoff` |
 
-```text
-/plugin marketplace add suboss87/fdeops
-/plugin install fdeops@fdeops
-```
+These examples are starting points, not a required sequence. The catalog also covers inherited projects, business cases, incidents, recovery, source connections and multiple customer records. `fde` uses the same instructions and loads additional detail only when needed.
 
-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.
+**Which mode should I choose?** Use an individual skill for a specific task. Use `fde` when you want help across several tasks and a continuing customer record. Installing a skill makes it available independently; it does not remove its real input requirements. For example, `dashboard` needs records to display, while `debrief` can review pasted notes without saving anything.
 
-</details>
+<a name="how-skills-work"></a>
 
-<details>
-<summary><b>Cursor</b></summary>
+## Keep a customer record
 
-After installing the skill, add the FDEOps instructions to the **client workspace** you have open:
+An **engagement** is your ongoing project with a customer. Its record lives in a separate folder on your machine, outside the customer's application code:
 
-```bash
-npx fdeops adapters .
+```text
+~/fde-engagements/client01/.fde/
 ```
 
-See [adapters/](adapters/README.md).
+The files are readable Markdown. They track what the customer asked for, who can decide, what success means, what changed, and the evidence behind each result. You can inspect, copy or keep them if you stop using FDEOps.
+
+After a meeting, paste permitted notes into the same agent conversation. It proposes the new requests, decisions, unresolved questions and next actions. Correct anything it misunderstood, then confirm the update.
 
-</details>
+A request is not automatically an agreement. A passing test is not a production deployment. A measured improvement is not customer acceptance. FDEOps keeps those distinctions in the record.
 
-<details>
-<summary><b>Codex, other agents, and offline setup</b></summary>
+At the next session, the coordinator retrieves a short summary rather than loading the full history. The default summary is capped at 16 KiB; older evidence is retrieved when needed. This cap applies to FDEOps output, not everything your agent loads.
 
-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:
+If your agent cannot start the record, run this in your terminal from the workspace where you work on that customer:
 
 ```bash
 npx fdeops resume --init client01
 ```
 
-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).
-
-</details>
-
+This links that workspace to the customer's record. [Daily use and meeting walkthrough](docs/USAGE.md) · [Record format](docs/schema.md).
 
 <a name="what-a-working-day-looks-like"></a>
 
 ## Your daily fieldbook
 
-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.
+The fieldbook is a read-only browser view of your customer records. It shows next actions, open risks, missing evidence and results waiting for acceptance.
+
+![FDEOps fieldbook showing next actions and delivery gaps across fictional customers](media/fieldbook-preview.png)
 
-![Dark FDEOps fieldbook showing next actions and delivery gaps across fictional clients](media/fieldbook-preview.png)
+Run this in your terminal to view all your customers:
 
 ```bash
 npx fdeops dashboard --all --open
 ```
 
-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.
-
-**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`.
-
-⭐ If FDEOps makes your client work easier, star the repo.
-
----
-
-<a name="from-the-first-meeting-to-handover"></a>
-
-## Commands
-
-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`.
-
-| 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 |
-
-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).
-
-You can also just say it: “Prep me for the sponsor meeting,” “What did we agree about scope?” or “Help me hand this over.”
-
----
-
-## Engagement workflows
-
-Thirty-four workflows, 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.
-
-Full detail: [docs/skills-reference.md](docs/skills-reference.md).
+Open a customer's record and copy an action into your agent to continue. Run the command again after updates to refresh the view.
 
-### Land
+**Try a fictional example first:** `npx fdeops demo` runs sample meeting notes through review and produces a fieldbook without using an AI model. It creates or resets its demo folder under `~/fde-engagements/.demo/`. Remove that example with `npx fdeops demo --clean`.
 
-| Skill | What it does | Use when |
-|--------|--------------|----------|
-| [land](skills/fde/references/land.md) | Interrogate the brief | New client, first meeting, just got the brief |
-| [audit](skills/fde/references/audit.md) | Verify inherited claims | Taking over, previous consultant left |
-| [who-decides](skills/fde/references/who-decides.md) | Map decision rights | Need to know who matters |
-| [earn-trust](skills/fde/references/earn-trust.md) | Earn access | Need access or credibility |
-| [hold-scope](skills/fde/references/hold-scope.md) | Hold scope | "Also can you…", timeline unchanged |
+## Fit it to the project
 
-### Discover
+For a small task, use the supplied notes or code and return the result. For an ongoing project, use the customer record. For enterprise work, include the relevant teams, access rules, release checks and operating responsibilities in the plan.
 
-| Skill | What it does | Use when |
-|--------|--------------|----------|
-| [discover](skills/fde/references/discover.md) | Frame the problem | Brief feels wrong, shadow processes |
-| [test-assumptions](skills/fde/references/test-assumptions.md) | Test assumptions | Brief feels too neat |
-| [score-use-cases](skills/fde/references/score-use-cases.md) | Score use cases | Everything is P0 |
-| [poc](skills/fde/references/poc.md) | Validate the solution | POC, spike, need to de-risk |
+The pack includes implementation, integration, debugging and QA instructions. It uses the repository's existing tools. It does not supply customer credentials, infrastructure, specialist approvals or production authority.
 
-### Plan
+Optional setup:
 
-| Skill | What it does | Use when |
-|--------|--------------|----------|
-| [plan](skills/fde/references/plan.md) | Sequence the work | What order, what is done |
-| [business-case](skills/fde/references/business-case.md) | Build the business case | Defend budget or timeline |
-| [three-options](skills/fde/references/three-options.md) | Generate options | "What should we do?" |
-| [pick-three](skills/fde/references/pick-three.md) | Prioritize three | Everything is urgent |
+- **Personal preferences:** `npx fdeops setup` records how you work and what to mask before sharing context.
+- **Repository reconnaissance:** `npx fdeops scan` reads local files and returns an initial assessment and questions. It does not change the repository.
+- **Other agent hosts:** [Adapters](adapters/README.md) add a pointer to the coordinator in your workspace.
+- **External sources:** [Connection recipes](mcp/recipes/) explain how to pull permitted material from tools you already use.
 
-### Ship
-
-| Skill | What it does | Use when |
-|--------|--------------|----------|
-| [build](skills/fde/references/build.md) | Implement the increment | A scoped change in their repository |
-| [integrate](skills/fde/references/integrate.md) | Prove the system boundary | APIs, imports and write-back |
-| [debug](skills/fde/references/debug.md) | Reproduce and repair a failure | Unexpected behavior or a regression |
-| [qa](skills/fde/references/qa.md) | Exercise the delivered journey | Functional acceptance or browser QA |
-| [ship](skills/fde/references/ship.md) | Release with evidence | Ready for an authorized rollout |
-| [what-breaks](skills/fde/references/what-breaks.md) | Assess impact | Touching shared infrastructure |
-| [rescue](skills/fde/references/rescue.md) | Resolve the incident | Down, or they went quiet |
-| [review](skills/fde/references/review.md) | Review the change | Before merge, scope creep |
-| [rollback](skills/fde/references/rollback.md) | Rehearse rollback | "We can always revert" |
-
-### Outcome
-
-| Skill | What it does | Use when |
-|--------|--------------|----------|
-| [readout](skills/fde/references/readout.md) | Report the outcome | Friday, sponsor update |
-| [demo-prep](skills/fde/references/demo-prep.md) | Prepare the demo | Demo or exec walkthrough |
-| [debrief](skills/fde/references/debrief.md) | Capture the meeting | Just left a meeting |
-| [board-memo](skills/fde/references/board-memo.md) | Brief the board | Justify continued investment |
-| [dashboard](skills/fde/references/dashboard.md) | Open the fieldbook | This customer, or all of them |
-| [ingest](skills/fde/references/ingest.md) | Ingest sources | Transcript, Notion, Slack |
-| [connect](skills/fde/references/connect.md) | Connect a source | Connect Granola |
-
-### Close
-
-| Skill | What it does | Use when |
-|--------|--------------|----------|
-| [close](skills/fde/references/close.md) | Transfer operations | Wrapping up |
-| [runbook](skills/fde/references/runbook.md) | Write the runbook | They must operate without you |
-| [switch-clients](skills/fde/references/switch-clients.md) | Switch engagements | 2+ clients |
-| [encode-pattern](skills/fde/references/encode-pattern.md) | Encode the pattern | It will apply again |
-| [red-team](skills/fde/references/red-team.md) | Challenge the plan | "Poke holes in this" |
-
-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).
-
-Optional pull: you add the source MCP; we **pull** on request. [mcp/recipes/](mcp/recipes/)
-
----
-
-<a name="use-the-cli-directly"></a>
-
-## How Skills Work
-
-One `@fde`. One file per situation. One folder per client.
-
-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.
-
-A request stays a request until agreed. A staging result stays separate from production. Recording a result does not mean the customer accepted it.
-
-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.
-
-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.
-
-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).
-
----
-
-## Engagement memory (`.fde/`)
-
-One folder per client. Plain markdown. Grep it, copy it, take it into a meeting.
-
-| 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 |
-
-Schema: [docs/schema.md](docs/schema.md). Fieldbook: `npx fdeops dashboard --open` (bound) or `--all --open` (portfolio).
-
----
-
-## Who this is for
-
-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.
-
-If your work has no client commitments or operating handover to track, a simpler project note may be enough.
+Use the [installation guide](docs/install.md) for the full pack, Claude Code hooks, offline setup and upgrading from earlier versions.
 
 <a name="your-records-your-control"></a>
 
 ## Your data stays yours
 
-The CLI works with local files and Git, without network calls or telemetry. Client records remain readable Markdown if you stop using FDEOps.
-
-Your AI host may send the material it reads to its configured model. CLI context and smart proposals mask common email, phone, SSN-shaped, and credential patterns locally; this is not complete PII detection. 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.
+The CLI reads local files and Git, with no network calls or telemetry. Installation through `npx` may download packages. Your AI host may send material it reads to its configured model.
 
-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.
+FDEOps masks common sensitive patterns and excludes `<private>` blocks from CLI, dashboard and hook outputs. This is not complete sensitive-data detection. Do not ask the agent to read private blocks directly, and use only material allowed by the customer's AI policy.
 
-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.
+You review proposed decisions. Enabled session hooks can save mechanical session progress automatically; direct CLI write commands update records when you run them.
 
-[Privacy](PRIVACY.md) · [Security](SECURITY.md)
+[Privacy](PRIVACY.md) · [Security](SECURITY.md) · [What has been tested and its limits](docs/verification.md)
 
-## Principles
-
-- **Who signs** - name who can accept the work.
-- **Brief vs real job** - check what happens on the floor, not only the slide.
-- **Back from done** - agree how you will test success before planning the build.
-- **Their staging, then live** - prove the change and agree the release and rollback.
-- **Promised, measured, accepted** - keep each separate, with its evidence.
-- **They run it** - hand over the knowledge and ownership, not just the code.
-- **The kit says what to check. You still decide.**
-
----
+## Who this is for
 
-<a name="find-your-way-around"></a>
+Forward deployed engineers, consultants and small delivery teams working with customers across meetings, codebases and operating environments. The pack supports the engineering and customer work together. Its checks help expose missing evidence; they do not replace professional judgment or prove every deployment safe.
 
-## Project Structure
+## Find your way around
 
 | You want to… | Start here |
 |---|---|
-| Install or use FDEOps | [docs/](docs/README.md) |
-| Understand or change a workflow | [skills/fde/](skills/fde/SKILL.md) and its `references/` |
-| Work on the CLI or fieldbook | [bin/](bin/) and [test/](test/) |
-| Walk through a client engagement | [examples/](examples/) |
-| Check what has been tested | [evals/](evals/) and [verification](docs/verification.md) |
-
-[Full repository map](docs/REPO_LAYOUT.md).
-
----
-
-<a name="contribute"></a>
-
-## 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 upgrade | [Installation](docs/install.md) |
+| Work through your first customer project | [Usage](docs/USAGE.md) and [examples](examples/) |
+| Explore the instructions | [Skill reference](docs/skills-reference.md) |
+| Understand the repository | [Repository layout](docs/REPO_LAYOUT.md) |
+| Check the test evidence | [Verification](docs/verification.md) |
+| Improve the pack | [Contributing](CONTRIBUTING.md) |
 
-Skills should be **specific** (actionable steps), **verifiable** (an artifact in `.fde/`), and **minimal**. The `fde` CLI stays local-only.
+Built by [Subash Natarajan](https://www.linkedin.com/in/subashn/). [Issues](https://github.com/suboss87/fdeops/issues) · [Discussions](https://github.com/suboss87/fdeops/discussions)
 
 ## License
 
-MIT - use these skills on client work.
+MIT. Use FDEOps in your customer work. See [LICENSE](LICENSE).

package/bin/catalog-doc.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+const fs = require('node:fs')
+const path = require('node:path')
+const catalog = require('./skill-catalog')
+const root = path.resolve(__dirname, '..')
+const inputs = {
+  context: 'Supplied notes, code or evidence',
+  records: 'Existing customer records + CLI',
+  source: 'Host source tools or setup documentation',
+  'record-write': 'Notes or source tools; selected record for staging/saving',
+}
+const cell = value => value.replace(/\|/g, '\\|').replace(/\n/g, ' ')
+function renderCatalog(items = catalog) {
+  const out = ['# FDEOps skills', '', `**${items.length} task skills + one coordinator, \`fde\` = ${items.length + 1} installable skills.**`, '',
+    'Every task below can be installed and used directly. Ask `fde` to select the relevant skills when working across a customer project. The groups help you find a task; they are not required phases.', '',
+    'Install a task with `npx skills add suboss87/fdeops --skill <name>`, replacing `<name>` with its catalog name. See [installation](install.md#individual-skills-and-the-full-pack) for the full pack and host-specific invocation.', '',
+    'Customer records live at `~/fde-engagements/<customer>/.fde/`. A skill provides instructions, not customer credentials or infrastructure. Drafting from supplied notes does not need a customer record. Viewing records does; staging or saving requires the intended customer and applicable confirmation.', '']
+  for (const group of [...new Set(items.map(item => item.group))]) {
+    out.push(`## ${group}`, '', '| Skill | Use it when | Result | Input needed |', '|---|---|---|---|')
+    for (const item of items.filter(item => item.group === group)) {
+      out.push(`| [${item.name}](../skills/${item.name}/SKILL.md) | ${cell(item.description)} | ${cell(item.result)} | ${inputs[item.inputMode]} |`)
+    }
+    out.push('')
+  }
+  out.push('## Domain guidance', '', 'The skills can apply supporting guidance for AI systems, financial services, healthcare, government work and customer-facing artifacts when relevant. These references are included instructions, not additional installable skills or a substitute for the responsible specialists.', '', '[Starting examples](skills.md) · [Customer records](schema.md) · [Verification and limits](verification.md)', '')
+  return out.join('\n')
+}
+function checkCatalog(base = root) {
+  const file = path.join(base, 'docs/skills-reference.md')
+  if (fs.readFileSync(file, 'utf8') !== renderCatalog()) throw new Error('Public skill catalog is stale; run npm run generate:skills')
+  const readme = fs.readFileSync(path.join(base, 'README.md'), 'utf8')
+  if (!readme.includes(`**${catalog.length} task skills + one coordinator, \`fde\`**`)) throw new Error('README skill count differs from the catalog')
+}
+module.exports = { renderCatalog, checkCatalog }
+if (require.main === module) {
+  if (process.argv.includes('--check')) checkCatalog()
+  else fs.writeFileSync(path.join(root, 'docs/skills-reference.md'), renderCatalog())
+}

package/bin/check.js

@@ -115,9 +115,8 @@ for (const refFile of mentioned) {
 }
 ok(`router dispatch (${mentioned.length} reference targets verified) + memory contract`)
 
-// Public claims must match the router. The docs advertise a method count and a
-// per-domain list; both drifted from SKILL.md once (ingest / connect
-// routed but undocumented), and a number nobody can verify is worse than none.
+// Public names, routed instructions, installation entries and generated docs
+// must agree. A task must never be advertised without a usable package.
 {
   // Every routing row must parse. A row this misses is a method that could go
   // undocumented for free, so an unparsed row is a hard failure, not a silent skip.
@@ -150,55 +149,23 @@ ok(`router dispatch (${mentioned.length} reference targets verified) + memory co
       fail(`check.js cannot read the method name in a SKILL.md routing row: ${line.trim().slice(0, 80)}`)
       continue
     }
+    const entry = catalog.find(item => item.name === method)
+    const target = (line.match(/references\/([a-z0-9-]+)\.md/) || [])[1]
+    if (entry && entry.method !== target) fail(`Router points ${method} at ${target}, expected ${entry.method}`)
     routed.add(method)
   }
   if (!routed.size) fail('check.js could not parse the SKILL.md routing table')
 
-  // docs/skills-reference.md is the canonical per-skill list: one row per
-  // skill inside the six stage tables, ending at the Overlays section.
-  const reference = read('docs/skills-reference.md')
-  const documented = new Set()
-  let documentedRows = 0
-  for (const line of reference.split('### Overlays')[0].split('\n')) {
-    const m = line.match(/^\|\s*\[([a-z0-9-]+)\]\(\.\.\/skills\/fde\/references\/([a-z0-9-]+\.md)\)/)
-    if (!m) continue
-    documentedRows++
-    documented.add(m[1])
-    // A link nobody followed is the same unverifiable claim this gate exists for:
-    // the target must exist, and it must be the skill the text names.
-    if (m[2] !== `${m[1]}.md`) {
-      fail(`docs/skills-reference.md links [${m[1]}] at references/${m[2]}`)
-    } else if (!fs.existsSync(path.join(root, 'skills', 'fde', 'references', m[2]))) {
-      fail(`docs/skills-reference.md links references/${m[2]}, which does not exist`)
-    }
-  }
-  if (documented.size !== documentedRows) {
-    fail(`docs/skills-reference.md lists ${documentedRows} skill rows for ${documented.size} skills - a duplicate row inflates the count`)
-  }
-  const undocumented = [...routed].filter(name => !documented.has(name))
-  if (undocumented.length) {
-    fail(`SKILL.md routes skill(s) missing from docs/skills-reference.md: ${undocumented.join(', ')}`)
-  }
-  // and the other direction: a documented skill nothing routes to is a skill
-  // the agent can never reach, advertised anyway.
-  const unrouted = [...documented].filter(name => !routed.has(name))
-  if (unrouted.length) {
-    fail(`docs/skills-reference.md documents skill(s) SKILL.md never routes to: ${unrouted.join(', ')}`)
-  }
-  for (const rel of ['docs/skills.md', 'docs/skills-reference.md']) {
-    const body = read(rel)
-    // `-` is a word boundary, so \bscore\b matches inside `score-use-cases`:
-    // a skill could disappear from the docs behind a hyphenated sibling.
-    const absent = [...documented].filter(name => !new RegExp(`(?<![\\w-])${name}(?![\\w-])`).test(body))
-    if (absent.length) fail(`${rel} does not list skill(s): ${absent.join(', ')}`)
-    const claims = [...body.matchAll(/(\d+)\s+workflows/g)].map(m => Number(m[1]))
-    if (!claims.length) fail(`${rel} must state how many workflows it documents`)
-    const wrong = [...new Set(claims.filter(n => n !== documented.size))]
-    if (wrong.length) {
-      fail(`${rel} claims ${wrong.join('/')} skills; ${documented.size} are documented`)
-    }
+  // Every routed task is installable and every public entry is reachable.
+  const names = new Set(catalog.map(item => item.name))
+  for (const name of routed) if (!names.has(name)) fail(`Routed task has no installable skill: ${name}`)
+  for (const item of catalog) {
+    if (!routed.has(item.name)) fail(`Installable skill has no coordinator route: ${item.name}`)
+    if (!router.includes(`references/${item.method}.md`)) fail(`Missing canonical instruction for ${item.name}`)
   }
-  ok(`public skill count is verifiable (${documented.size} documented, ${routed.size} routed)`)
+  if (names.size !== catalog.length || new Set(catalog.map(item => item.method)).size !== catalog.length) fail('Duplicate public skill name or method')
+  try { require('./catalog-doc').checkCatalog(); ok('Public catalog matches installable skills') }
+  catch (error) { fail(error.message) }
 
   const refDir = path.join(root, 'skills', 'fde', 'references')
   const extra = fs.readdirSync(refDir).filter(f => f.endsWith('.md') && !mentioned.includes(f))
@@ -560,10 +527,14 @@ if (plugin.commands !== './.claude/commands' || plugin.skills !== './skills') {
 } else {
   for (const cmd of ['brief', 'discover', 'plan', 'ship', 'outcome', 'close', 'debrief', 'prep', 'trust', 'receipts', 'readout']) {
     const rel = `.claude/commands/${cmd}.md`
-    if (!fs.existsSync(path.join(root, rel))) fail(`${rel} missing`)
+    const task = catalog.find(item => item.name === cmd)
+    if (task) {
+      if (!fs.existsSync(path.join(root, 'skills', cmd, 'SKILL.md'))) fail(`Missing command skill: ${cmd}`)
+      if (fs.existsSync(path.join(root, rel))) fail(`Duplicate command and task skill: ${cmd}`)
+    } else if (!fs.existsSync(path.join(root, rel))) fail(`${rel} missing`)
     else if (!read(rel).includes('@fde')) fail(`${rel} must load @fde`)
   }
-  ok('slash commands load @fde')
+  ok('Task commands have one entry; legacy engagement shortcuts load @fde')
 }
 
 if (!fs.existsSync(path.join(root, 'mcp', 'fdeops-ingest', 'server.js'))) {

package/bin/fde.js

@@ -569,8 +569,8 @@ function withFileLock(targetPath, fn, opts = {}) {
           console.error(msg)
           process.exit(1)
         }
-        const waitUntil = Date.now() + 20
-        while (Date.now() < waitUntil) { /* spin */ }
+        // This CLI is synchronous; yield CPU while the other writer finishes.
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20)
         continue
       }
       if (opts.soft) throw e