fdeops 5.0.0 → 5.1.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - working in the fdeops repository
 
-This repository **is** FDEOps: skills for Forward Deployed Engineers. The `fde` coordinator selects the relevant instructions for customer work. Fourteen task skills also work individually. The local CLI manages customer records in `.fde/` files; users confirm consequential judgments.
+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
 

package/README.md

@@ -6,7 +6,7 @@
 
 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.
 
-A **skill** is a set of instructions your AI coding agent follows. FDEOps includes **14 task skills** you can use individually and **one `fde` coordinator** that chooses the right task as a customer project progresses.
+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.
 
 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.
 
@@ -54,32 +54,30 @@ an incoming request today, where time goes, and what we still need to ask.
 
 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.
 
-**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 14 separate names to your agent's skill menu.
+**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.
 
 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).
 
-## Task skills
-
-A customer **workflow** means the steps people and systems take to finish a job: receive a request, check its details, make a decision, and update the relevant system. These skills help with different parts of that work.
-
-| What you need to do | Skill | What you get |
-|---|---|---|
-| Find the real problem behind a customer request | `discover` | Current steps, delays, baseline and unanswered questions |
-| Decide what to do with an additional request | `scope` | Impact on agreed work and a recommended commitment |
-| Choose how to solve the problem | `options` | Feasible approaches, trade-offs and a recommendation |
-| Test an assumption before committing to a build | `poc` | A limited test, its evidence and the next decision |
-| Implement an agreed software change | `build` | Code, checks and a clear account of what changed |
-| Connect the customer's systems | `integrate` | An integration checked for mapping, permissions and failed or repeated requests |
-| Find and fix a failure | `debug` | A reproduced problem, repair and regression checks |
-| Check a proposed code change | `review` | Specific findings tied to code and expected behavior |
-| Check an AI system's answers or actions | `evaluate` | Evaluation cases, results and remaining limits |
-| Test what users actually experience | `qa` | Runtime or browser evidence, including failure cases |
-| Prepare and carry out an authorized release | `ship` | Release checks, recovery steps and deployment evidence |
-| Explain progress to the customer sponsor | `readout` | What was promised, what was measured and what was accepted |
-| Leave the team able to operate the system | `handoff` | Responsibilities, operating instructions and readiness gaps |
-| Turn a deployment lesson into reusable learning | `feedback` | A supported product recommendation or reusable pattern |
-
-These are entry points, not a required sequence. `fde` also handles meeting debriefs, stakeholder decisions, planning, incidents and other situations through its [full skill reference](docs/skills-reference.md). It loads the relevant instructions as needed.
+## Choose a skill
+
+<a name="task-skills"></a>
+
+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 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.
 
 <a name="how-skills-work"></a>
 

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

package/bin/generate-skills.js

@@ -31,8 +31,16 @@ function referencesFor(method, referenceRoot = source) {
   }
   return [...found].sort()
 }
+const inputGuidance = {
+  context: 'Work directly from the supplied permitted context. Standalone work does not require an engagement folder or initialization. Record filenames in the method are optional persistence destinations when no engagement is bound.',
+  records: 'This task operates on existing engagement records. Use the local CLI and permitted sanitized packets; do not invent a portfolio or initialize records merely to complete the task. Report missing records or access as a limitation.',
+  source: 'Source configuration and capability checks do not require an engagement record. Use available host tools and source documentation. Any later record staging or application follows the ingest method and its binding and confirmation requirements.',
+  'record-write': 'Use permitted supplied material or available source tools to prepare a sourced proposal without requiring an engagement record. CLI staging and reconciliation use a bound engagement; applying updates requires the bound record and confirmation. Do not claim an unbound draft has been saved to engagement memory.',
+}
 function entrypoint(item) {
-  return `---\nname: ${item.name}\ndescription: ${item.description}\n---\n\n# ${item.name}\n\n<!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->\n\n## Purpose\n\n${item.description}\n\nRead [the task context contract](references/task-context.md), then [the method](references/${item.method}.md). Load further references only when the task needs them. Everything linked is included in this skill; no other skill pack is required.\n\n## Principles\n\n- Work directly from the supplied permitted context. Standalone work does not require an engagement folder or initialization. Record filenames in the method are optional persistence destinations when no engagement is bound.\n- If called by @fde, reuse its current sanitized packet and scope. Do not restart setup, discovery or questions already answered.\n- The task context contract controls persistence and authority in both modes. Preserve unknowns and distinguish implementation, verification, deployment and acceptance.\n- Use the customer's repository instructions and available tools. Report a missing capability or unrun check honestly; do not claim that installing a skill provisions infrastructure.\n`
+  const mode = item.inputMode || 'context'
+  if (!Object.hasOwn(inputGuidance, mode)) throw new Error(`Invalid input mode: ${mode}`)
+  return `---\nname: ${item.name}\ndescription: ${item.description}\n---\n\n# ${item.name}\n\n<!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->\n\n## Purpose\n\n${item.description}\n\nRead [the task context contract](references/task-context.md), then [the method](references/${item.method}.md). Load further references only when the task needs them. Everything linked is included in this skill; no other skill pack is required.\n\n## Principles\n\n- ${inputGuidance[mode]}\n- If called by @fde, reuse its current sanitized packet and scope. Do not restart setup, discovery or questions already answered.\n- The task context contract controls persistence and authority in both modes. Preserve unknowns and distinguish implementation, verification, deployment and acceptance.\n- Use the customer's repository instructions and available tools. Report a missing capability or unrun check honestly; do not claim that installing a skill provisions infrastructure.\n`
 }
 function expectedFiles(item, referenceRoot = source) {
   const files = new Map([['SKILL.md', entrypoint(item)]])

package/bin/install.js

@@ -11,7 +11,12 @@ const CLAUDE_MD_SRC = path.join(__dirname, '..', 'CLAUDE.md.template')
 const FDE_TEMPLATES_SRC = path.join(__dirname, '..', 'templates', '.fde')
 const ADAPTERS_SRC = path.join(__dirname, '..', 'adapters')
 const TASK_NAMES = new Set(require('./skill-catalog').map(item => item.name))
-const RENAMED_SKILLS = new Set([...TASK_NAMES].map(name => `fde-${name}`))
+// Only these published task packages changed names. New catalog entries must
+// not acquire historical migration authority over unrelated prefixed skills.
+const RENAMED_SKILLS = new Set([
+  'discover', 'scope', 'options', 'poc', 'build', 'integrate', 'debug',
+  'review', 'evaluate', 'qa', 'ship', 'readout', 'handoff', 'feedback',
+].map(name => `fde-${name}`))
 const LIB_SRC = path.join(__dirname, 'lib')
 
 const GLOBAL_SKILLS_DIR = path.join(os.homedir(), '.claude', 'skills')
@@ -135,8 +140,8 @@ function removeLegacySkills(opts = {}) {
 // Keep edits and additions outside the discovery directory, without guessing which
 // individual files are personal. Unmarked third-party installs require manual cleanup.
 function archiveRenamedSkill(name) {
-  if (!TASK_NAMES.has(name)) return
   const oldName = `fde-${name}`
+  if (!RENAMED_SKILLS.has(oldName)) return
   const old = path.join(GLOBAL_SKILLS_DIR, oldName)
   checkPath(old)
   if (!fs.existsSync(old)) return
@@ -163,7 +168,8 @@ function installSkillDirs(opts = {}) {
   for (const entry of fs.readdirSync(SKILLS_SRC, { withFileTypes: true })) {
     const src = path.join(SKILLS_SRC, entry.name)
     const dest = path.join(GLOBAL_SKILLS_DIR, entry.name)
-    if (!entry.isDirectory()) { copyFile(src, dest); continue }
+    // Repository-level documentation is not an installable skill.
+    if (!entry.isDirectory()) continue
     if (isLink(dest)) { links.push(entry.name); continue }
     try {
       checkTree(src, dest)

package/bin/skill-catalog.js

@@ -1,17 +1,284 @@
-// Public entry points. Methods remain authored once in skills/fde/references/.
+// One public task catalog. Methods remain authored once in skills/fde/references/.
+// inputMode distinguishes supplied-context tasks from operations that use engagement records.
 module.exports = [
-  ['discover', 'discover', 'Trace a customer workflow and identify the problem, baseline and evidence gaps. Use for discovery or an unclear customer brief, before choosing a solution.'],
-  ['scope', 'hold-scope', 'Assess a new customer request against agreed scope, trade-offs and ownership. Use when an engagement expands or a custom feature needs a commitment decision.'],
-  ['options', 'three-options', 'Compare feasible approaches to a customer problem and recommend a path with costs, constraints and evidence. Use for an architecture or delivery decision, not implementation.'],
-  ['poc', 'poc', 'Run a bounded customer proof of concept to test a consequential uncertainty. Use for a spike or pilot with a question and decision deadline, not a full rollout.'],
-  ['build', 'build', '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.'],
-  ['integrate', 'integrate', 'Build or change a customer-system integration with explicit data mapping, permissions, retries and reconciliation. Use for connectors, imports, write-back and upstream APIs.'],
-  ['debug', 'debug', 'Investigate and repair a reproducible failure in a customer integration or application. Use for diagnosis and regression prevention; follow incident authority for live mitigation.'],
-  ['review', 'review', 'Review a proposed customer code change against its intended outcome and operational risks. Use for a diff or PR review; report evidence and actionable findings.'],
-  ['evaluate', 'eval-pack', 'Evaluate an AI workflow against representative cases and its permitted actions. Use for model, retrieval or agent evaluation; tests do not grant release authority.'],
-  ['qa', 'qa', 'Exercise the delivered customer journey using real runtime or browser evidence. Use for functional acceptance testing after implementation, including failure paths.'],
-  ['ship', 'ship', 'Prepare or execute an authorized controlled release with verified checks, recovery and an operating owner. Use when a customer increment is ready for deployment.'],
-  ['readout', 'readout', 'Prepare a sponsor update separating promised outcomes, measured results and customer acceptance. Use for progress readouts or defending a delivery claim.'],
-  ['handoff', 'close', 'Transfer operation of a customer deployment with ownership, evidence and a tested support path. Use for handoff or an engineer rotation, not merely code delivery.'],
-  ['feedback', 'encode-pattern', 'Assess a field lesson for reuse or product feedback without exposing customer context. Use for recurring deployment lessons; distinguish a hypothesis from a validated pattern.'],
-].map(([name, method, description]) => ({ name, method, description }))
+  {
+    "name": "brief",
+    "method": "land",
+    "group": "Start",
+    "result": "A grounded brief with success criteria and open questions.",
+    "description": "Clarify a new customer brief, desired outcome, constraints and evidence gaps. Use for kickoff or a first meeting; do not repeat discovery already supplied.",
+    "inputMode": "context"
+  },
+  {
+    "name": "audit",
+    "method": "audit",
+    "group": "Start",
+    "result": "An audit of inherited claims and takeover risks.",
+    "description": "Audit an inherited engagement or implementation against its evidence. Use when taking over work or joining mid-project; distinguish verified facts from inherited claims.",
+    "inputMode": "context"
+  },
+  {
+    "name": "who-decides",
+    "method": "who-decides",
+    "group": "Start",
+    "result": "A stakeholder map with decision rights and unknowns.",
+    "description": "Map stakeholders, decision rights, influence and blockers from supplied evidence. Use when ownership is unclear or the stakeholder landscape changes.",
+    "inputMode": "context"
+  },
+  {
+    "name": "earn-trust",
+    "method": "earn-trust",
+    "group": "Start",
+    "result": "A plan for access, credibility and permitted AI use.",
+    "description": "Plan how to earn customer trust and appropriate access. Use when credibility, permissions or AI policy constrain the engagement.",
+    "inputMode": "context"
+  },
+  {
+    "name": "discover",
+    "method": "discover",
+    "description": "Trace a customer workflow and identify the problem, baseline and evidence gaps. Use for discovery or an unclear customer brief, before choosing a solution.",
+    "group": "Discover",
+    "result": "A workflow diagnosis with baseline and evidence gaps.",
+    "inputMode": "context"
+  },
+  {
+    "name": "test-assumptions",
+    "method": "test-assumptions",
+    "group": "Discover",
+    "result": "A ranked set of assumptions and ways to test them.",
+    "description": "Challenge a proposed solution by identifying and testing consequential assumptions. Use when the brief feels too certain or discovery reveals contradictions.",
+    "inputMode": "context"
+  },
+  {
+    "name": "score-use-cases",
+    "method": "score-use-cases",
+    "group": "Discover",
+    "result": "A ranked use-case shortlist with evidence and trade-offs.",
+    "description": "Compare competing customer use cases by value, feasibility and evidence. Use when several problems compete for delivery capacity.",
+    "inputMode": "context"
+  },
+  {
+    "name": "poc",
+    "method": "poc",
+    "description": "Run a bounded customer proof of concept to test a consequential uncertainty. Use for a spike or pilot with a question and decision deadline, not a full rollout.",
+    "group": "Discover",
+    "result": "A bounded experiment with evidence and a decision.",
+    "inputMode": "context"
+  },
+  {
+    "name": "scope",
+    "method": "hold-scope",
+    "description": "Assess a new customer request against agreed scope, trade-offs and ownership. Use when an engagement expands or a custom feature needs a commitment decision.",
+    "group": "Plan",
+    "result": "A scope decision with trade-offs and ownership.",
+    "inputMode": "context"
+  },
+  {
+    "name": "options",
+    "method": "three-options",
+    "description": "Compare feasible approaches to a customer problem and recommend a path with costs, constraints and evidence. Use for an architecture or delivery decision, not implementation.",
+    "group": "Plan",
+    "result": "Compared approaches and an evidence-backed recommendation.",
+    "inputMode": "context"
+  },
+  {
+    "name": "plan",
+    "method": "plan",
+    "group": "Plan",
+    "result": "A sequenced delivery plan with owners and acceptance checks.",
+    "description": "Sequence an understood outcome into verifiable delivery slices with dependencies, ownership and acceptance checks. Use for delivery planning, estimation or migration strategy.",
+    "inputMode": "context"
+  },
+  {
+    "name": "business-case",
+    "method": "business-case",
+    "group": "Plan",
+    "result": "An evidence-backed investment case with explicit assumptions.",
+    "description": "Develop a business case for an initiative using costs, benefits, risks and evidence. Use when a sponsor needs budget or timeline justification.",
+    "inputMode": "context"
+  },
+  {
+    "name": "prioritize",
+    "method": "pick-three",
+    "group": "Plan",
+    "result": "Three immediate priorities and explicit deferrals.",
+    "description": "Choose up to three immediate priorities from competing initiatives. Use when everything is urgent and the customer needs a defensible order with explicit deferrals.",
+    "inputMode": "context"
+  },
+  {
+    "name": "red-team",
+    "method": "red-team",
+    "group": "Plan",
+    "result": "A critique of weak claims, failure modes and corrective actions.",
+    "description": "Stress-test a plan, brief or delivery claim against evidence and plausible failure modes. Use when the user asks for a red team or preparation for a consequential decision.",
+    "inputMode": "context"
+  },
+  {
+    "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.",
+    "group": "Build and verify",
+    "result": "An implemented change with verification evidence.",
+    "inputMode": "context"
+  },
+  {
+    "name": "integrate",
+    "method": "integrate",
+    "description": "Build or change a customer-system integration with explicit data mapping, permissions, retries and reconciliation. Use for connectors, imports, write-back and upstream APIs.",
+    "group": "Build and verify",
+    "result": "An integration with tested mapping and failure handling.",
+    "inputMode": "context"
+  },
+  {
+    "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.",
+    "group": "Build and verify",
+    "result": "A diagnosed failure, repair and regression evidence.",
+    "inputMode": "context"
+  },
+  {
+    "name": "review",
+    "method": "review",
+    "description": "Review a proposed customer code change against its intended outcome and operational risks. Use for a diff or PR review; report evidence and actionable findings.",
+    "group": "Build and verify",
+    "result": "Actionable findings tied to the intended outcome.",
+    "inputMode": "context"
+  },
+  {
+    "name": "evaluate",
+    "method": "eval-pack",
+    "description": "Evaluate an AI workflow against representative cases and its permitted actions. Use for model, retrieval or agent evaluation; tests do not grant release authority.",
+    "group": "Build and verify",
+    "result": "Evaluation results, failure analysis and release evidence.",
+    "inputMode": "context"
+  },
+  {
+    "name": "qa",
+    "method": "qa",
+    "description": "Exercise the delivered customer journey using real runtime or browser evidence. Use for functional acceptance testing after implementation, including failure paths.",
+    "group": "Build and verify",
+    "result": "Customer-journey evidence and acceptance gaps.",
+    "inputMode": "context"
+  },
+  {
+    "name": "what-breaks",
+    "method": "what-breaks",
+    "group": "Build and verify",
+    "result": "A blast-radius assessment and mitigation plan.",
+    "description": "Assess the impact of a proposed change on dependencies and shared infrastructure. Use before touching unfamiliar or consequential systems.",
+    "inputMode": "context"
+  },
+  {
+    "name": "rollback",
+    "method": "rollback",
+    "group": "Build and verify",
+    "result": "A rollback drill with recovery evidence and remaining gaps.",
+    "description": "Prepare and rehearse a recovery path for an intended release. Use when rollback is assumed, untested or previously failed; follow the environment authority for any drill.",
+    "inputMode": "context"
+  },
+  {
+    "name": "ship",
+    "method": "ship",
+    "description": "Prepare or execute an authorized controlled release with verified checks, recovery and an operating owner. Use when a customer increment is ready for deployment.",
+    "group": "Build and verify",
+    "result": "A controlled release result with recovery and ownership.",
+    "inputMode": "context"
+  },
+  {
+    "name": "readout",
+    "method": "readout",
+    "description": "Prepare a sponsor update separating promised outcomes, measured results and customer acceptance. Use for progress readouts or defending a delivery claim.",
+    "group": "Report",
+    "result": "A sponsor update separating promises, results and acceptance.",
+    "inputMode": "context"
+  },
+  {
+    "name": "demo-prep",
+    "method": "demo-prep",
+    "group": "Report",
+    "result": "A demo narrative, rehearsal plan and failure fallback.",
+    "description": "Prepare a customer demo or executive walkthrough around an evidenced outcome. Use before show-and-tell to rehearse the journey and prepare a fallback.",
+    "inputMode": "context"
+  },
+  {
+    "name": "debrief",
+    "method": "debrief",
+    "group": "Report",
+    "result": "A sourced meeting summary with decisions and next actions.",
+    "description": "Turn meeting notes or a transcript into sourced decisions, changes and next actions. Use after a customer conversation; review consequential record updates before saving.",
+    "inputMode": "context"
+  },
+  {
+    "name": "board-memo",
+    "method": "board-memo",
+    "group": "Report",
+    "result": "An executive memo separating evidence, risk and decisions.",
+    "description": "Draft a board or executive summary of an engagement using outcomes, risks and investment decisions. Use when the sponsor needs to brief senior leadership.",
+    "inputMode": "context"
+  },
+  {
+    "name": "rescue",
+    "method": "rescue",
+    "group": "Operate",
+    "result": "A recovery plan and evidence of authorized mitigation.",
+    "description": "Triage an outage, loss of stakeholder trust or a failing engagement direction. Use for urgent recovery; distinguish diagnosis from authorized production mitigation.",
+    "inputMode": "context"
+  },
+  {
+    "name": "dashboard",
+    "method": "dashboard",
+    "group": "Operate",
+    "result": "A portfolio view of engagement status and attention needed.",
+    "description": "Review the portfolio across existing engagement records. Use for status across customers; requires accessible permitted records and does not create missing client histories.",
+    "inputMode": "records"
+  },
+  {
+    "name": "switch-clients",
+    "method": "switch-clients",
+    "group": "Operate",
+    "result": "A refreshed client binding and cross-client triage.",
+    "description": "Switch between existing customer engagements and triage competing needs. Use when context switching causes confusion; requires engagement records and preserves one client per write.",
+    "inputMode": "records"
+  },
+  {
+    "name": "runbook",
+    "method": "runbook",
+    "group": "Operate",
+    "result": "An operating runbook with recovery steps and ownership.",
+    "description": "Write an operating runbook from the delivered system and verified procedures. Use when the customer team or a successor needs to operate without the original engineer.",
+    "inputMode": "context"
+  },
+  {
+    "name": "handoff",
+    "method": "close",
+    "description": "Transfer operation of a customer deployment with ownership, evidence and a tested support path. Use for handoff or an engineer rotation, not merely code delivery.",
+    "group": "Operate",
+    "result": "An operating handoff with ownership and a support path.",
+    "inputMode": "context"
+  },
+  {
+    "name": "feedback",
+    "method": "encode-pattern",
+    "description": "Assess a field lesson for reuse or product feedback without exposing customer context. Use for recurring deployment lessons; distinguish a hypothesis from a validated pattern.",
+    "group": "Operate",
+    "result": "A reusable field lesson with evidence and privacy boundaries.",
+    "inputMode": "context"
+  },
+  {
+    "name": "connect",
+    "method": "connect",
+    "group": "Operate",
+    "result": "Source setup guidance and an honest capability check.",
+    "description": "Configure or diagnose access to a requested source using available host tools. Use for source MCP setup; source configuration needs no engagement record and credentials stay with the host.",
+    "inputMode": "source"
+  },
+  {
+    "name": "ingest",
+    "method": "ingest",
+    "group": "Operate",
+    "result": "Sourced proposed updates, with confirmed record application when bound.",
+    "description": "Fetch requested source material and prepare sourced engagement updates. Use to catch up from external notes or messages; applying updates requires a bound record and confirmation.",
+    "inputMode": "record-write"
+  }
+]

package/mcp/fdeops-ingest/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops-ingest-mcp",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "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.0.0",
+  "version": "5.1.0",
   "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",
@@ -11,7 +11,7 @@
     "test": "node --test test/*.test.js",
     "test:skill-routing": "node evals/skill-routing/check.js && node evals/skill-routing/live-smoke.js",
     "prepublishOnly": "node bin/check.js && npm test",
-    "generate:skills": "node bin/generate-skills.js"
+    "generate:skills": "node bin/generate-skills.js && node bin/catalog-doc.js"
   },
   "files": [
     "bin/",