fdeops 5.1.7 → 5.1.9

package/README.md

@@ -4,183 +4,154 @@
 
 <a name="why-use-it"></a>
 
-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.
+The codebase does not tell your agent what the customer agreed to last week, why an approach was rejected or who can approve the next release.
 
-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.
+FDEOps brings that context into the work, from the first meeting to a system the customer can run. Use a skill for one task, or let `fde` coordinate the project and keep its record.
 
-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.
+**35 task skills + one coordinator, `fde`**. Use your existing tools and processes. You and the customer keep control of the decisions.
 
-[Get started](#quick-start) · [Choose a task](#task-skills) · [Keep a customer record](#keep-a-customer-record) · [Documentation](docs/README.md)
+[Get started](#quick-start) · [What it helps with](#three-things-it-helps-with) · [Choose a skill](#task-skills) · [Data boundaries](#your-records-your-control) · [Docs](docs/README.md)
 
-<img width="1000" height="586" alt="fdeops-flow" src="https://github.com/user-attachments/assets/12bbec6a-d0b3-4d03-81aa-4b842731a044" />
+<img width="1000" height="586" alt="FDEOps engagement flow from customer discovery through delivery and handover" src="https://github.com/user-attachments/assets/12bbec6a-d0b3-4d03-81aa-4b842731a044" />
 
 ## Quick start
 
-**Use customer-approved data and AI tools.** The CLI runs locally, but your AI agent may send what it reads to its provider. Masking is partial and does not protect direct file reads or pasted text. If approval is unclear, start with synthetic data. Anonymised customer material still needs permission. See [safe setup and limits](SECURITY.md#before-customer-work).
+**Use customer-approved data and AI tools.** Your agent may send what it reads to its provider, even though the FDEOps CLI runs locally. If approval is unclear, use fictional data. [Safe setup](SECURITY.md#before-customer-work).
 
-Use FDEOps with an AI coding agent that supports skills. Start with one task, or let `fde` coordinate a customer project.
+### Let `fde` coordinate a customer project
 
-Try the fictional engagement first with `npx fdeops demo` (requires Node.js 18+ and Git; may download the package). It creates or resets a separate `.demo` workspace and does not need customer data.
-
-### Work on a customer project
-
-Run this in the terminal where your coding agent runs, then select your agent in the installer:
+Install in the terminal where your AI coding agent runs, then select your agent:
 
 ```bash
 npx skills add suboss87/fdeops --skill fde
 ```
 
-This installation method uses Node.js (which includes `npx`) and Git. If either is missing, ask your agent to help with setup. The FDEOps CLI requires Node.js 18 or later. See [installation options](docs/install.md) for your agent.
-
-Then select `fde` in your agent and start a conversation. In agents that support `@fde`, use:
+Select `fde` in your agent, or use `@fde` where supported:
 
 ```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: …
+Help me prepare for the first meeting. Here is the brief: ...
 ```
 
-`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.
-
-For an ongoing project, naming the customer starts a local 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).
+The coordinator uses the relevant instructions as the work changes. You do not need to choose a skill at each step. For an ongoing project, it keeps decisions, evidence and next actions in a local customer record.
 
-### Use just one task
-
-For example, install only `discover`:
+### Use one skill for one task
 
 ```bash
-npx skills add suboss87/fdeops --skill discover
+npx skills add suboss87/fdeops --skill debrief
 ```
 
 Then ask your agent:
 
 ```text
-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.
+Use FDEOps debrief to review these meeting notes.
+Separate decisions, requests and open questions. Return a draft only.
 [Paste notes you are permitted to share.]
 ```
 
-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.
+No customer record is needed for this draft. Each task includes its required instructions; you do not need to install `fde` or another pack.
 
-**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.
+These installation commands use Node.js and Git; the optional record CLI requires Node.js 18+. See [installation and upgrades](docs/install.md) for host-specific invocation, the full pack and alternatives. Installing `fde` includes all underlying instructions, but does not add the 35 separate task names to your agent's menu.
 
-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).
+**Try it with fictional data:** `npx fdeops demo` runs sample notes through review and creates a fieldbook without calling an AI model. It requires Node.js 18+ and Git, may download the package, and creates or resets only its separate `.demo` workspace. [Five-minute walkthrough](docs/USAGE.md#new-here-5-minutes).
 
-## Choose a skill
+## Three things it helps with
 
-<a name="task-skills"></a>
+### 1. Starting the next session without starting over
 
-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.
-
-| 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` |
-
-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.
-
-**Which mode should I choose?** Use an individual skill for a specific task. Use `fde` when you want help selecting the next task or maintaining a continuing customer record. You can also ask it for a one-off result without creating records. 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.
+A repository tells you where the code lives. It may not tell you why the customer rejected an approach, which access is still blocked or what the team promised on Tuesday.
 
+<a name="keep-a-customer-record"></a>
 <a name="how-skills-work"></a>
 
-## Keep a customer record
+For an ongoing engagement, FDEOps keeps a separate plain-Markdown record at `~/fde-engagements/<customer>/.fde/`. The coordinator retrieves a bounded summary and looks up details when needed. A saved implementation checkpoint points back to the current task record; the agent checks it before continuing.
 
-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:
+Use [debrief](skills/debrief/SKILL.md) after a meeting and [switch-clients](skills/switch-clients/SKILL.md) when changing customers. [How records work](docs/USAGE.md).
 
-```text
-~/fde-engagements/client01/.fde/
-```
+### 2. Keeping a request from becoming an agreement
 
-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.
+A stakeholder asks for more scope. A demo looks promising. Neither establishes a new commitment or an accepted result.
 
-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.
+FDEOps separates requests, confirmed decisions, reported results and unresolved questions. You review proposed record changes before confirming them. Dates and sources make a claim traceable; they do not authenticate customer approval.
 
-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.
+For example, these fictional notes:
 
-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. For interrupted implementation, it also surfaces a saved checkpoint when one exists, then checks the current task record before continuing. This cap applies to FDEOps output, not everything your agent loads.
+> Mara agreed to keep CSV upload this phase. Devon asked for real-time sync; Mara has not answered. Two staging runs took 12 minutes. Production has not been measured.
 
-If your agent cannot start the record, run this in your terminal from the workspace where you work on that customer:
+A review should keep those distinctions:
 
-```bash
-npx fdeops resume --init client01
-```
+| Record | What the notes support |
+|---|---|
+| Decision | Keep CSV upload this phase; attributed to Mara in the supplied notes |
+| Request | Real-time sync remains unapproved |
+| Evidence | Two staging runs took 12 minutes; production benefit is unmeasured |
+| Next step | Resolve the scope request with Mara before changing the commitment |
 
-This links that workspace to the customer's record. [Daily use and meeting walkthrough](docs/USAGE.md) · [Record format](docs/schema.md).
+This is a draft, not a saved agreement. Use [who-decides](skills/who-decides/SKILL.md), [scope](skills/scope/SKILL.md) or [readout](skills/readout/SKILL.md) for the decision in front of you.
 
-<a name="what-a-working-day-looks-like"></a>
+### 3. Knowing what is actually ready
 
-## Your daily fieldbook
+A local test, a deployed change and a customer-accepted result answer different questions.
 
-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 carries the agreed checks into implementation and binds verification to the relevant revision and environment. Release guidance asks for operating limits, recovery evidence and an owner. Missing access or evidence stays visible; a passing local test does not fill that gap.
 
-![FDEOps fieldbook showing next actions and delivery gaps across fictional customers](media/fieldbook-preview.png)
+Use [build](skills/build/SKILL.md), [integrate](skills/integrate/SKILL.md), [review](skills/review/SKILL.md), [ship](skills/ship/SKILL.md) and [handoff](skills/handoff/SKILL.md) as needed. [See the tests and their limits](docs/verification.md).
 
-Run this in your terminal to view all your customers:
+## Choose a skill
 
-```bash
-npx fdeops dashboard --all --open
-```
+<a name="task-skills"></a>
 
-Open a customer's record and copy an action into your agent to continue. Run the command again after updates to refresh the view.
+| Work in front of you | Start with |
+|---|---|
+| An unclear customer request | `brief`, `discover` |
+| Unclear ownership or access | `who-decides`, `earn-trust` |
+| A decision about scope or approach | `scope`, `options`, `plan` |
+| An implementation or system connection | `build`, `integrate` |
+| A failure or a result to verify | `debug`, `review`, `qa`, `evaluate` |
+| A release or operating handover | `ship`, `runbook`, `handoff` |
+| Meeting notes or a customer update | `debrief`, `readout` |
 
-**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`.
+These are entry points, not a required sequence. Every task can be called directly or selected by `fde`. Some tasks need records to work with: `dashboard` displays saved records, while `debrief` can review supplied notes without saving them. [Full skill catalog](docs/skills-reference.md).
 
-## Fit it to the project
+<a name="what-a-working-day-looks-like"></a>
 
-Start with the work in front of you:
+<details>
+<summary><strong>View your customer records in the fieldbook</strong></summary>
 
-| Project | How to use FDEOps |
-|---|---|
-| Small fix or analysis | Give a task skill the relevant notes or code. Get the result and its verification; no customer record is required. |
-| Customer integration or ongoing delivery | Use `fde` to connect discovery, implementation, tests and updates in one continuing record. |
-| Enterprise engagement | Work within the customer’s existing access, change-control and operating processes. Record who can approve each decision and what evidence they require. |
+The fieldbook is a read-only browser view of next actions, risks, evidence gaps and results awaiting acceptance.
 
-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.
+![Fieldbook showing fictional customer records](media/fieldbook-preview.png)
 
-Optional setup:
+```bash
+npx fdeops dashboard --all --open
+```
 
-- **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.
+Copy an action into your agent to continue. Regenerate the view after record updates. [Daily use](docs/USAGE.md).
 
-Use the [installation guide](docs/install.md) for the full pack, Claude Code hooks, offline setup and upgrading from earlier versions.
+</details>
 
 <a name="your-records-your-control"></a>
+<a name="your-data-stays-yours"></a>
 
-## Your data stays yours
-
-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.
+## Local records, explicit data boundaries
 
-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 reads local files and Git without network calls or telemetry. Installation may download packages. Your AI host controls model connections and may transmit what it reads.
 
-You review proposed decisions. Enabled session hooks can save mechanical session progress automatically; direct CLI write commands update records when you run them.
+CLI and hook outputs mask common identifier patterns. `<private>` blocks are redacted from those outputs and the dashboard. Local reports retain unmarked identifiers by default. Masking is partial; raw file reads and pasted text bypass it. Anonymisation does not grant permission to use customer material.
 
-[Privacy](PRIVACY.md) · [Security](SECURITY.md) · [What has been tested and its limits](docs/verification.md)
+You review consequential record updates. Enabled hooks can save mechanical session progress; direct CLI write commands update records when run. [Privacy](PRIVACY.md) · [Security](SECURITY.md) · [Local-model results](docs/verification.md#local-model-results).
 
 ## Who this is for
 
-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.
+Forward deployed engineers, consultants and delivery teams working across customer meetings, codebases and operating environments. Start with one task or coordinate an ongoing engagement. The skills use your existing tools and processes; they do not provide infrastructure, access rights or customer approval.
 
-## Find your way around
+## Go deeper
 
-| You want to… | Start here |
-|---|---|
-| 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) |
+[Install or upgrade](docs/install.md) · [Daily use](docs/USAGE.md) · [Worked examples](examples/) · [Skill catalog](docs/skills-reference.md) · [Source connections](mcp/recipes/) · [Repository layout](docs/REPO_LAYOUT.md) · [Verification](docs/verification.md) · [Contribute](CONTRIBUTING.md)
 
-Built by [Subash Natarajan](https://www.linkedin.com/in/subashn/). [Issues](https://github.com/suboss87/fdeops/issues) · [Discussions](https://github.com/suboss87/fdeops/discussions)
+Built and maintained 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 FDEOps in your customer work. See [LICENSE](LICENSE).
+[MIT](LICENSE). Use FDEOps in your customer work.

package/bin/generate-skills.js

@@ -4,6 +4,7 @@ const fs = require('node:fs')
 const path = require('node:path')
 const { createHash } = require('node:crypto')
 const catalog = require('./skill-catalog')
+const { interfaceYaml } = require('./skill-ui')
 const root = path.resolve(__dirname, '..')
 const source = path.join(root, 'skills/fde/references')
 
@@ -44,6 +45,8 @@ function entrypoint(item) {
 }
 function expectedFiles(item, referenceRoot = source) {
   const files = new Map([['SKILL.md', entrypoint(item)]])
+  const ui = interfaceYaml(item.name, item.ui)
+  if (ui) files.set('agents/openai.yaml', ui)
   for (const ref of referencesFor(item.method, referenceRoot)) files.set(`references/${ref}`, fs.readFileSync(path.join(referenceRoot, ref), 'utf8'))
   return files
 }
@@ -59,7 +62,7 @@ function walk(dir, prefix = '') {
     const rel = prefix + e.name
     if (e.isSymbolicLink() || (!e.isDirectory() && !e.isFile()) || (e.isFile() && fs.lstatSync(path.join(dir, e.name)).nlink > 1)) throw new Error(`Unsafe generated path: ${path.join(dir, e.name)}`)
     if (e.isDirectory()) {
-      if (rel !== 'references') throw new Error(`Unowned generated directory: ${path.join(dir, e.name)}`)
+      if (rel !== 'references' && rel !== 'agents') throw new Error(`Unowned generated directory: ${path.join(dir, e.name)}`)
       entries.push(...walk(path.join(dir, e.name), rel + '/'))
     } else entries.push(rel)
   }
@@ -103,7 +106,7 @@ function generate(check = false, options = {}) {
         if (manifest.generator !== 'bin/generate-skills.js' || manifest.version !== 1 || !manifest.files || Array.isArray(manifest.files) || typeof manifest.files !== 'object') throw new Error(`Invalid ownership manifest: ${name}`)
         owned = manifest.files
         for (const [rel, hash] of Object.entries(owned)) {
-          if (!/^(?:SKILL\.md|references\/[a-z][a-z-]*\.md)$/.test(rel) || !/^[a-f0-9]{64}$/.test(hash)) throw new Error(`Invalid ownership entry: ${name}/${rel}`)
+          if (!/^(?:SKILL\.md|agents\/openai\.yaml|references\/[a-z][a-z-]*\.md)$/.test(rel) || !/^[a-f0-9]{64}$/.test(hash)) throw new Error(`Invalid ownership entry: ${name}/${rel}`)
         }
       } else {
         // Migrate 4.1.0 packages conservatively: only the marked entry and exact
@@ -138,11 +141,11 @@ function generate(check = false, options = {}) {
       fs.mkdirSync(path.dirname(path.join(dest, rel)), { recursive: true })
       fs.writeFileSync(path.join(dest, rel), body)
     }
-    if (!output.size) {
-      const refs = path.join(dest, 'references')
-      if (stat(refs)) fs.rmdirSync(refs)
-      fs.rmdirSync(dest)
+    for (const directory of ['references', 'agents']) {
+      const target = path.join(dest, directory)
+      if (stat(target)?.isDirectory() && fs.readdirSync(target).length === 0) fs.rmdirSync(target)
     }
+    if (!output.size) fs.rmdirSync(dest)
   }
 }
 module.exports = { referencesFor, expectedFiles, generate }

package/bin/skill-catalog.js

@@ -116,7 +116,7 @@ module.exports = [
   {
     "name": "build",
     "method": "build",
-    "description": "Implement a scoped customer-facing software change in the existing repository and verify its behavior. Use for delivery work with an understood outcome, not incident response.",
+    "description": "Implement a scoped software change for a customer and verify its behavior. Use for delivery work with an understood outcome, not incident response.",
     "group": "Build and verify",
     "result": "An implemented change with verification evidence.",
     "inputMode": "context"
@@ -132,7 +132,7 @@ module.exports = [
   {
     "name": "debug",
     "method": "debug",
-    "description": "Investigate and repair a reproducible failure in a customer integration or application. Use for diagnosis and regression prevention; follow incident authority for live mitigation.",
+    "description": "Investigate a failure, regression or incorrect result in an integration or application, even before it can be reproduced. Use for diagnosis and repair; follow incident authority for live mitigation.",
     "group": "Build and verify",
     "result": "A diagnosed failure, repair and regression evidence.",
     "inputMode": "context"

package/bin/skill-ui.js

@@ -0,0 +1,47 @@
+// Optional host UI metadata. Task routing and methods live in skill-catalog.js.
+const entries = {
+  brief: ['Customer Brief', 'Clarify the outcome, constraints, and evidence', 'clarify this customer brief and its open questions'],
+  audit: ['Engagement Audit', 'Check inherited claims against delivery evidence', 'audit this inherited engagement and its risks'],
+  'who-decides': ['Who Decides', 'Map stakeholders and decision ownership', 'map the stakeholders and decision rights for this work'],
+  'earn-trust': ['Earn Trust', 'Plan credible next steps and appropriate access', 'plan how to earn trust and appropriate customer access'],
+  discover: ['Discover', 'Trace the workflow and identify the real problem', 'trace this customer workflow and identify evidence gaps'],
+  'test-assumptions': ['Test Assumptions', 'Find consequential assumptions and test them', 'identify and test the assumptions behind this proposal'],
+  'score-use-cases': ['Score Use Cases', 'Compare customer use cases and their trade-offs', 'compare these customer use cases using the available evidence'],
+  poc: ['Proof of Concept', 'Test a delivery uncertainty with a bounded pilot', 'design a bounded proof of concept for this uncertainty'],
+  scope: ['Scope', 'Assess new requests against agreed commitments', 'assess this request against the agreed scope'],
+  options: ['Delivery Options', 'Compare feasible approaches to a customer problem', 'compare feasible approaches and recommend a delivery path'],
+  plan: ['Delivery Plan', 'Sequence delivery into verifiable increments', 'turn this agreed outcome into a sequenced delivery plan'],
+  'business-case': ['Business Case', 'Connect investment decisions to costs and evidence', 'develop a business case with explicit assumptions'],
+  prioritize: ['Prioritize', 'Choose immediate priorities and explicit deferrals', 'choose the immediate priorities from this competing work'],
+  'red-team': ['Red Team', 'Challenge a plan with evidence and failure modes', 'stress-test this plan and identify corrective actions'],
+  build: ['Build', 'Implement and verify an agreed software change', 'implement this scoped change and verify the agreed behavior'],
+  integrate: ['Integrate', 'Prove system connections and failure handling', 'implement this integration and verify its downstream result'],
+  debug: ['Debug', 'Investigate failures and verify the repair', 'investigate this failure using the available evidence'],
+  review: ['Code Review', 'Review a change for delivery and operational risks', 'review this change against its outcome and operational risks'],
+  evaluate: ['Evaluate AI', 'Measure AI workflow behavior and failure modes', 'evaluate this AI workflow using representative cases'],
+  qa: ['Journey QA', 'Verify the real customer journey and its results', 'exercise the changed customer journey and report evidence'],
+  'what-breaks': ['What Breaks', 'Assess the blast radius before changing a system', 'assess the impact of this change on dependent systems'],
+  rollback: ['Rollback', 'Rehearse recovery and expose remaining gaps', 'prepare a recovery drill within the permitted environment'],
+  ship: ['Ship', 'Prepare a controlled release with recovery evidence', 'prepare this increment for an authorized release'],
+  readout: ['Sponsor Readout', 'Separate promises, measured results, and acceptance', 'prepare a sponsor readout from the delivery evidence'],
+  'demo-prep': ['Demo Prep', 'Rehearse an evidenced demo with a fallback', 'prepare a customer demo and its failure fallback'],
+  debrief: ['Meeting Debrief', 'Extract sourced decisions and next actions', 'turn these meeting notes into sourced decisions and actions'],
+  'board-memo': ['Board Memo', 'Draft an executive account of outcomes and risks', 'draft an executive memo from the engagement evidence'],
+  rescue: ['Rescue', 'Triage urgent delivery and engagement failures', 'triage this failing engagement and identify recovery steps'],
+  dashboard: ['Engagement Dashboard', 'Review status across existing engagement records', 'review the portfolio using available engagement records'],
+  'switch-clients': ['Switch Clients', 'Refresh customer context and triage competing needs', 'switch to the requested engagement and refresh its context'],
+  runbook: ['Operating Runbook', 'Document verified operations and recovery steps', 'draft an operating runbook from these verified procedures'],
+  handoff: ['Handoff', 'Transfer operation with evidence and clear ownership', 'prepare an operating handoff with evidence and ownership'],
+  feedback: ['Field Feedback', 'Assess field lessons for safe and useful reuse', 'assess this field lesson for reuse or product feedback'],
+  connect: ['Connect a Source', 'Check source setup and available host capabilities', 'check the requested source connection and available capabilities'],
+  ingest: ['Ingest Notes', 'Prepare sourced engagement updates for review', 'prepare sourced engagement updates from this requested material'],
+}
+
+function interfaceYaml(name, fields = entries[name]) {
+  if (!fields) return null
+  const [displayName, shortDescription, prompt] = fields
+  if (typeof displayName !== 'string' || !displayName.trim() || typeof shortDescription !== 'string' || shortDescription.length < 25 || shortDescription.length > 64 || typeof prompt !== 'string' || !prompt.trim()) throw new Error(`Invalid skill UI metadata: ${name}`)
+  // JSON string literals are also YAML double-quoted scalars; no parser dependency.
+  return `interface:\n  display_name: ${JSON.stringify(displayName)}\n  short_description: ${JSON.stringify(shortDescription)}\n  default_prompt: ${JSON.stringify(`Use $${name} to ${prompt}.`)}\n`
+}
+module.exports = { entries, interfaceYaml }

package/mcp/fdeops-ingest/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops-ingest-mcp",
-  "version": "5.1.7",
+  "version": "5.1.9",
   "private": true,
   "description": "Thin stdio MCP sink for FDEOps ingest (stage \u2192 propose \u2192 apply). Zero runtime dependencies.",
   "bin": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops",
-  "version": "5.1.7",
+  "version": "5.1.9",
   "description": "Forward deployed engineering skills for AI coding agents. Use focused task skills or @fde for discovery, implementation, verification and handoff, with local engagement records.",
   "bin": {
     "fdeops": "bin/install.js",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "fdeops",
-  "version": "5.1.7",
+  "version": "5.1.9",
   "description": "Forward deployed engineering skills for AI coding agents. Use focused task skills or @fde for discovery, implementation, verification and handoff, with local engagement records.",
   "author": {
     "name": "Subash Natarajan",

package/skills/audit/.fde-generated.json

@@ -3,6 +3,7 @@
   "version": 1,
   "files": {
     "SKILL.md": "b0dee139ba4f681a61eb0c3d8c802f06857502fd479843edb8e3b8cb27229ae5",
+    "agents/openai.yaml": "3b08e2e6a4149545da08238463955501bc60b7bf628cf4e344e893330590bbde",
     "references/audit.md": "ed32ea78cbccb100742dd838e8cf4cd4b6f33ad44b3de7424fc624670d571dbc",
     "references/discover.md": "f65aa11a539b4dbbed70cfaa94ec2a35595aa9a2d0282790510b933ac9c721ce",
     "references/task-context.md": "9066514a50043f3ad888d133d4e8b89b7132551e098cf2c80203c458a80126e5"

package/skills/audit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Engagement Audit"
+  short_description: "Check inherited claims against delivery evidence"
+  default_prompt: "Use $audit to audit this inherited engagement and its risks."

package/skills/board-memo/.fde-generated.json

@@ -3,6 +3,7 @@
   "version": 1,
   "files": {
     "SKILL.md": "5782488d9878335cdc1db68c08eccd613486370164284ff11d93422eced6423a",
+    "agents/openai.yaml": "a3ce2dc79d3732da6c9aa2d45d09541c09c8f7bdf44f34c6603b5dbaf8624095",
     "references/board-memo.md": "44eb3c27f164da63af694591025b3fc96bb23d149c29de400997c1653e3322f8",
     "references/business-case.md": "32e000e8351cd59f9eaad8be40babb276df69948ea4f81e01a4672e47f48cb25",
     "references/task-context.md": "9066514a50043f3ad888d133d4e8b89b7132551e098cf2c80203c458a80126e5"

package/skills/board-memo/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Board Memo"
+  short_description: "Draft an executive account of outcomes and risks"
+  default_prompt: "Use $board-memo to draft an executive memo from the engagement evidence."

package/skills/brief/.fde-generated.json

@@ -3,6 +3,7 @@
   "version": 1,
   "files": {
     "SKILL.md": "5d88b9818951f8a8a44c39ad2b36ccdca74fef5e6ed31e67788b50d3ca1bb006",
+    "agents/openai.yaml": "8dc0b43545004419bad49e1d50cd3beb968bbcc24baacdaf7fb7304a5fd03bba",
     "references/land.md": "7a82ac999d23b51b602cd815777a853c4879ca8be40dc6c84c66f154d1f77951",
     "references/task-context.md": "9066514a50043f3ad888d133d4e8b89b7132551e098cf2c80203c458a80126e5"
   }

package/skills/brief/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Customer Brief"
+  short_description: "Clarify the outcome, constraints, and evidence"
+  default_prompt: "Use $brief to clarify this customer brief and its open questions."

package/skills/build/.fde-generated.json

@@ -2,12 +2,13 @@
   "generator": "bin/generate-skills.js",
   "version": 1,
   "files": {
-    "SKILL.md": "245c53b404549ed73fd6ef532e48c002de7d20a6a93eaca6c0714c4e4d14ba92",
-    "references/build.md": "7634abd02b70011b7443a65ea3aaf3cb536ed5b051312aed188f46523deea7f9",
-    "references/debug.md": "c3bb344d38cc3552cb4e230c601a9be3fe173af2b2efb89aab6b7b04339f24f4",
+    "SKILL.md": "77570e69b8d708d60cd6ab1dcc79c95a75824ab668f60a83a0dedbe668de2a70",
+    "agents/openai.yaml": "abd0a33ab4efa25ea038932d37eae2faa2527baa96ebae8732ea90f1ebc3865e",
+    "references/build.md": "03c52eda90642c62053b53ef1e85c97b4e647600f454aee9da0e415c9d98903e",
+    "references/debug.md": "3273a921a98522431ae821a283814897270c719cbfab83d14b99175537d869e5",
     "references/eval-pack.md": "0590b85d3cae0903c6b1274540c92eaa2a4373047e8a0548d6942516ef0bb9e1",
-    "references/integrate.md": "d0de35a783902ca8b4762e3a42a14f467766d56a928c3a5cf11adac2a6ba90ba",
-    "references/qa.md": "d8f58e6d36436469a58aeb1107037f3e27fa81ff5b82d0e4df3c23eeadaf683c",
+    "references/integrate.md": "1cb7a60d7545b0bf224fce678a04ce6ccdf368c47877d9c8e4dc4272bb0d5b0c",
+    "references/qa.md": "41de4d70827c83291efa217e97d777f62ec2849827687fbba7e4b1d17484b87e",
     "references/review.md": "55733ca868c00fb22110bc7b3ec7bb6c6451366c795073b19a2bccd30d2764c8",
     "references/ship.md": "95f51772b29de6f7d174f1f7678f15d46a3a5327dcb8facb94288e27907ae92c",
     "references/task-context.md": "9066514a50043f3ad888d133d4e8b89b7132551e098cf2c80203c458a80126e5",

package/skills/build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: build
-description: Implement a scoped customer-facing software change in the existing repository and verify its behavior. Use for delivery work with an understood outcome, not incident response.
+description: Implement a scoped software change for a customer and verify its behavior. Use for delivery work with an understood outcome, not incident response.
 ---
 
 # build
@@ -9,7 +9,7 @@ description: Implement a scoped customer-facing software change in the existing
 
 ## Purpose
 
-Implement a scoped customer-facing software change in the existing repository and verify its behavior. Use for delivery work with an understood outcome, not incident response.
+Implement a scoped software change for a customer and verify its behavior. Use for delivery work with an understood outcome, not incident response.
 
 Before investigating or acting:
 1. Read [the task context contract](references/task-context.md).

package/skills/build/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Build"
+  short_description: "Implement and verify an agreed software change"
+  default_prompt: "Use $build to implement this scoped change and verify the agreed behavior."

package/skills/build/references/build.md

@@ -1,22 +1,33 @@
 # build - Implement a verifiable increment
 
-**Enter when:** an agreed behavior needs implementation in an existing or new repository. For a broken behavior, start with [debug](debug.md); for a system boundary, use [integrate](integrate.md).
+Build the smallest complete change that demonstrates the agreed customer outcome through the real entry point.
 
-Use the permitted context and authority in [task context](task-context.md). This method works without `.fde/`; an existing engagement record can supply the same contract. Do not initialize memory just to write code.
+**Use when:** agreed behavior needs implementation in a new or existing repository. Use [debug](debug.md) for broken behavior and [integrate](integrate.md) for a system boundary.
 
-## Method
+Follow [task context](task-context.md). Supplied permitted context or an existing engagement record can provide the contract; do not initialize `.fde/` merely to write code.
 
-1. Identify the repository, its instructions, working tree, relevant callers, and test commands. Inspect examples before creating abstractions. Follow the repository's branch policy and choose any needed checkout isolation according to that policy and overlapping work. Preserve unrelated edits and state which dependencies or interfaces the change touches. Before changing an untested legacy path, capture the undocumented behavior callers depend on with targeted characterization checks; distinguish behavior to preserve from the intended change.
-2. State the observable outcome, constraints, and acceptance checks. Reuse agreed criteria for routine fixes. If a consequential product choice is unresolved, surface that choice while continuing independent investigation; do not invent acceptance.
-3. Choose the smallest coherent path that demonstrates the outcome through the real entry point. Include the necessary storage, error handling, and interface behavior in that slice. Name the failure that stops expansion and the recovery path for stateful changes.
-4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code. When changing dependencies, inspect the package source, requested version, lockfile changes and repository install-script policy before executing package code. Use the approved package manager and bootstrap controls; do not blanket-enable scripts or apply unrelated dependency upgrades.
-5. Add or update automated coverage for changed behavior when meaningful and feasible, including the relevant failure path. Existing tests must actually exercise the change; explain manual-only coverage and its limits. Run focused checks, then required repository checks. Exercise the actual affected journey with [QA](qa.md) when appropriate. For uncertain model behavior, use [eval-pack](eval-pack.md). Record results with [verification](verification.md), including checks that could not run.
-6. Inspect the final diff against the agreed outcome. If public behavior, interfaces, configuration or operating steps changed, update affected existing documentation and examples; exercise relevant commands or clearly mark checks that could not run. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
+## Understand the repository and outcome
 
-## Deliverable and acceptance
+Inspect repository instructions, working tree, relevant callers, examples, and test commands. Preserve unrelated edits. Follow its branch policy and choose checkout isolation according to overlapping work. Identify the dependencies and interfaces the change touches. Before changing an untested legacy path, use targeted characterization checks to capture undocumented behavior callers rely on; separate that behavior from the intended change.
 
-For substantial work, maintain the [recoverable checkpoint](verification.md#recoverable-checkpoint) in the existing task record as slices complete or work pauses.
+State the observable outcome, constraints, and acceptance checks, reusing agreed criteria for routine fixes. Surface unresolved consequential product choices while continuing independent investigation; do not invent acceptance.
 
-Return the implemented behavior, relevant paths, evidence, remaining limitations, and any decision needed. Done means the agreed checks have applicable evidence and the change is reviewable; passing tests does not imply deployment or customer acceptance. Committing, opening a PR, merging, and publishing happen only when the requested workflow authorizes those actions.
+## Build one complete slice
 
-When coordinated through `@fde`, record implementation and verification in the existing decisions/delivery records under their write rules. Standalone work can return the same receipt directly or use the repository's task record.
+Choose a coherent path through the real entry point, including its necessary storage, error handling, and interface behavior. Name the failure that would stop expansion and the recovery path for stateful changes.
+
+Use existing services, fixtures, validation, and repository conventions before adding alternatives. Limit cleanup to making the changed path understandable. For dependency changes, inspect the package source, requested version, lockfile changes, and install-script policy before executing package code. Use the approved package manager and bootstrap controls; do not blanket-enable scripts or include unrelated upgrades.
+
+## Demonstrate the behavior
+
+Add or update automated coverage when meaningful and feasible, including the relevant failure path. Check that existing tests actually exercise the change. Explain manual-only coverage and its limits. Run focused checks, then required repository checks; use [QA](qa.md) for the affected journey when appropriate and [eval-pack](eval-pack.md) for uncertain model behavior. Record evidence and unrun checks with [verification](verification.md).
+
+Inspect the final diff against the agreed outcome. Update affected existing documentation and examples when public behavior, interfaces, configuration, or operating steps change. Exercise relevant commands or state what could not run. For substantial or risky work, use [review](review.md) with a separate reviewer when available; label a self-check honestly. Reverify affected behavior after repairs.
+
+*Fictional example:* Northstar needs failed imports to be recoverable. A useful first slice takes one failed import through the existing retry action to a persisted result, including the retry's failure behavior. A new button alone does not demonstrate recovery.
+
+## Completion
+
+Return implemented behavior, relevant paths, evidence, limitations, and any decision needed. The change is ready when agreed checks have applicable evidence and the work is reviewable. Passing tests does not establish deployment or customer acceptance. Commit, open a PR, merge, or publish only when the requested workflow authorizes it.
+
+For substantial work, maintain a [recoverable checkpoint](verification.md#recoverable-checkpoint) in the existing task record as slices finish or work pauses. When coordinated through `@fde`, record implementation and verification in existing decisions/delivery records under their write rules. Standalone work can return the receipt directly or use the repository's task record.