fdeops 4.1.1 → 5.1.0

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)]])
@@ -63,12 +71,12 @@ function generate(check = false, options = {}) {
   const items = options.catalog || catalog
   const wanted = new Map()
   for (const item of items) {
-    if (!/^fde-[a-z-]+$/.test(item.name) || wanted.has(item.name)) throw new Error(`Invalid generated skill name: ${item.name}`)
+    if (!/^[a-z][a-z-]*$/.test(item.name) || item.name === 'fde' || item.name.startsWith('fde-') || wanted.has(item.name)) throw new Error(`Invalid generated skill name: ${item.name}`)
     wanted.set(item.name, expectedFiles(item, referenceRoot))
   }
   const rootStat = stat(skillRoot)
   if (rootStat && (!rootStat.isDirectory() || rootStat.isSymbolicLink())) throw new Error(`Unsafe skills root: ${skillRoot}`)
-  const names = new Set([...wanted.keys(), ...(rootStat ? fs.readdirSync(skillRoot).filter(n => /^fde-[a-z-]+$/.test(n)) : [])])
+  const names = new Set([...wanted.keys(), ...(rootStat ? fs.readdirSync(skillRoot).filter(n => n !== 'fde' && /^[a-z][a-z-]*$/.test(n)) : [])])
   const errors = []
   const plans = []
   for (const name of names) {

package/bin/install.js

@@ -10,6 +10,13 @@ const HOOKS_SRC = path.join(__dirname, '..', 'hooks')
 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))
+// 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')
@@ -115,7 +122,7 @@ function removeLegacySkills(opts = {}) {
   const skipped = []
   const links = []
   for (const dir of LEGACY_SKILL_DIRS) {
-    if (fs.existsSync(path.join(SKILLS_SRC, dir, 'SKILL.md'))) continue
+    if (RENAMED_SKILLS.has(dir) || fs.existsSync(path.join(SKILLS_SRC, dir, 'SKILL.md'))) continue
     const p = path.join(GLOBAL_SKILLS_DIR, dir)
     if (isLink(p)) { links.push(dir); continue }
     if (!fs.existsSync(path.join(p, 'SKILL.md'))) continue
@@ -129,6 +136,29 @@ function removeLegacySkills(opts = {}) {
   return { removed, skipped, links }
 }
 
+// Archive the complete previous package only after its replacement is installed.
+// 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) {
+  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
+  if (!isManaged(old)) {
+    installIncomplete = true
+    console.log(`  keep   ~/.claude/skills/${oldName} (ownership unknown; move it outside skills manually after reviewing ${name})`)
+    return
+  }
+  checkTree(old, old)
+  const archiveRoot = path.join(os.homedir(), '.claude', 'fdeops', 'skill-backups')
+  mkdir(archiveRoot)
+  const archive = fs.mkdtempSync(path.join(archiveRoot, `${oldName}-`))
+  try { fs.renameSync(old, path.join(archive, oldName)) }
+  catch (error) { fs.rmdirSync(archive); throw error }
+  console.log(`  archive ~/.claude/skills/${oldName} → ${path.join(archive, oldName)} (all previous content preserved)`)
+}
+
 // Copy each skill in, but never over a directory fdeops did not create.
 function installSkillDirs(opts = {}) {
   const skipped = []
@@ -138,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)
@@ -146,8 +177,10 @@ function installSkillDirs(opts = {}) {
       if (fs.existsSync(dest) && !isManaged(dest) && !opts.force) {
         // Installs predating the marker are still ours: adopt a same-named dir
         // whose SKILL.md is recognizably fdeops', so upgrades keep working.
-        if (!wasInstalledByUs(dest)) {
+        // Newly generic task names require an explicit marker, never a fingerprint.
+        if (TASK_NAMES.has(entry.name) || !wasInstalledByUs(dest)) {
           skipped.push(entry.name)
+          if (TASK_NAMES.has(entry.name)) installIncomplete = true
           continue
         }
         console.log(`  adopt  ~/.claude/skills/${entry.name} (earlier fdeops install)`)
@@ -156,6 +189,7 @@ function installSkillDirs(opts = {}) {
       // say it in human terms, place the rest, and exit non-zero at the end.
       copyDir(src, dest)
       markManaged(dest)
+      archiveRenamedSkill(entry.name)
     } catch (e) {
       failed.push({ name: entry.name, code: e.code || 'error', path: destPathFor(e.path, 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 = [
-  ['fde-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.'],
-  ['fde-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.'],
-  ['fde-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.'],
-  ['fde-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.'],
-  ['fde-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.'],
-  ['fde-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.'],
-  ['fde-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.'],
-  ['fde-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.'],
-  ['fde-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.'],
-  ['fde-qa', 'qa', 'Exercise the delivered customer journey using real runtime or browser evidence. Use for functional acceptance testing after implementation, including failure paths.'],
-  ['fde-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.'],
-  ['fde-readout', 'readout', 'Prepare a sponsor update separating promised outcomes, measured results and customer acceptance. Use for progress readouts or defending a delivery claim.'],
-  ['fde-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.'],
-  ['fde-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": "4.1.1",
+  "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": "4.1.1",
+  "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/",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "fdeops",
-  "version": "4.1.1",
+  "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.",
   "author": {
     "name": "Subash Natarajan",

package/skills/README.md

@@ -0,0 +1,7 @@
+# FDEOps skills
+
+Use any task folder directly, or use `fde` to coordinate a customer project. Each folder's `SKILL.md` explains when to use it and which inputs it needs.
+
+The [complete catalog](https://github.com/suboss87/FDEOps/blob/Main/docs/skills-reference.md) groups every installable skill by the work it supports. Start with the [README](../README.md) for installation and examples.
+
+For contributors: instructions are authored once under `fde/references/`. Task folders are generated from those instructions and `bin/skill-catalog.js`; run `npm run generate:skills` after changes. Keep private customer records outside this repository.

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

@@ -0,0 +1,10 @@
+{
+  "generator": "bin/generate-skills.js",
+  "version": 1,
+  "files": {
+    "SKILL.md": "aa120dd0b6c0781300d56f916f1721525de7fbe65608ff7a9a0239a2a5e20e88",
+    "references/audit.md": "ed32ea78cbccb100742dd838e8cf4cd4b6f33ad44b3de7424fc624670d571dbc",
+    "references/discover.md": "f65aa11a539b4dbbed70cfaa94ec2a35595aa9a2d0282790510b933ac9c721ce",
+    "references/task-context.md": "73eea2d7f164fac3226599e5be26ae4e79dcf69e0d24428dd12d623861410490"
+  }
+}

package/skills/audit/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: audit
+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.
+---
+
+# audit
+
+<!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->
+
+## Purpose
+
+Audit an inherited engagement or implementation against its evidence. Use when taking over work or joining mid-project; distinguish verified facts from inherited claims.
+
+Read [the task context contract](references/task-context.md), then [the method](references/audit.md). Load further references only when the task needs them. Everything linked is included in this skill; no other skill pack is required.
+
+## Principles
+
+- 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.
+- If called by @fde, reuse its current sanitized packet and scope. Do not restart setup, discovery or questions already answered.
+- The task context contract controls persistence and authority in both modes. Preserve unknowns and distinguish implementation, verification, deployment and acceptance.
+- 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.

package/skills/audit/references/discover.md

@@ -0,0 +1,112 @@
+# discover - Find the problem behind the request
+
+**Enter when:** the customer brief is unclear, the proposed solution may miss the real problem, or a change has exposed an unmapped part of the work.
+
+Apply [task context and evidence](task-context.md) first. Supplied notes are enough to begin. In an existing engagement, use permitted summaries of `context.md`, `brief.md`, `reality.md` and relevant `terrain.md` sections; extend existing findings instead of restarting.
+
+## Choose the depth the task needs
+
+- **Notes or meeting preparation:** return the current steps, observations, hypotheses and a few questions that would change the next decision. No repository scan, workshop or customer-record setup is required.
+- **A specific delivery problem:** follow the affected people, systems and data far enough to explain the break and identify what evidence is missing.
+- **A wider engagement:** map dependencies and decision owners across the involved teams. Examine each candidate problem before choosing where to invest; do not make a full enterprise inventory a prerequisite for one useful finding.
+
+State what you are investigating and which decision it informs. Reuse the user's stated goal. Ask only when a missing answer changes the next action; otherwise proceed with a clearly labelled provisional interpretation.
+
+## Frame the decision
+
+Write a short frame from the evidence available:
+
+| Part | What to establish |
+|---|---|
+| Situation | How people complete this task today |
+| Complication | The observed delay, failure, cost or constraint |
+| Question | The decision that further evidence should help someone make |
+| Possible outcomes | Confirm the brief, change its scope, investigate further or pause |
+
+Keep the question specific and neutral. “What causes requests to wait before assignment?” leaves room for different explanations. “How should we automate assignment?” assumes the solution before establishing the cause.
+
+Name the decision owner when known. An unknown owner or unmeasured baseline is a finding, not a reason to keep questioning indefinitely. Return a provisional frame and identify who or what could verify it. Do not present a new interpretation as agreed scope.
+
+## Trace the work
+
+Follow an ordinary case from arrival to completion, then relevant exceptions. Use the customer's terms for the request, system and people involved.
+
+For each step, establish:
+
+- Who performs it and where the input comes from.
+- What they do, check or decide, and which system they update.
+- Time spent working versus time spent waiting.
+- What happens when information is missing or the normal path fails.
+- Who notices the failure, how they recover, and which record they trust.
+
+Distinguish measured timings from estimates. A team lead's recollection is useful evidence about their experience; it is not a measured baseline. Do not infer that the slowest visible step causes the whole delay without following its dependencies.
+
+Use concrete questions when the supplied material leaves a gap: “Show me the last request that waited a day. What had to happen before someone could take it?” Ask about spreadsheets, manual transfers or other workarounds when there is evidence of them, without assuming they exist.
+
+When a workaround looks surprising, use the targeted history check in [audit](audit.md#before-changing-an-unfamiliar-workaround). History supplies clues, not proof that an old requirement still applies.
+
+## Inspect systems when relevant and permitted
+
+If the question depends on application behavior and code access is authorized, use `fde scan` and targeted file reads. If the CLI is unavailable, use the repository's existing search, Git and test tools. Do not load the whole repository or unrelated customer data.
+
+Follow the actual path: entry point → validation → processing → storage or downstream action. Inspect the code, configuration and tests that can explain the observed discrepancy.
+
+Check existing capability before proposing new work. A disabled feature, frequent edits or a missing nearby test is a lead to investigate, not proof of a root cause. Record the evidence behind any technical risk. When there is no repository access, state that implementation behavior remains unchecked and finish the work possible from the notes.
+
+## Check the data and dependencies the proposed work needs
+
+For each relevant source, establish where it lives, how fresh it is, who controls access, which fields the task needs, and what happens when it is unavailable. Inspect a permitted sample appropriate to the question; report its size and limitations rather than treating a small sample as representative by default.
+
+| Source or connection | Needed for | Freshness and quality evidence | Access owner | Failure or constraint | Next check |
+|---|---|---|---|---|---|
+| Fill only relevant sources | | | Unknown if unconfirmed | | |
+
+Check mappings between systems, supported APIs, permissions and retry behavior where they affect feasibility. A promised export or integration is not yet an available dependency. Record its responsible owner, verification date and required evidence when known; propose missing commitments for confirmation.
+
+For AI work, identify which steps can use deterministic logic, which need model judgment, and which require a human decision. Keep that allocation provisional until the affected owners agree. Establish who would operate the resulting change and what access or training they would need.
+
+## Use a workshop only when it resolves a real disagreement
+
+A short meeting with the relevant decision makers may help when teams describe different problems or constraints. Bring the observed cases and the decision to be made. Ask participants to state their constraints before discussing options.
+
+Summarize areas of agreement and disagreement. A vote or an absence of objections does not establish authority or acceptance. Ask the responsible owner to confirm the decision and record any unresolved objection, next action and date. Draft the summary promptly, then follow the record-confirmation rules before saving it.
+
+## Return a useful discovery result
+
+Use the smallest output that answers the user's request:
+
+1. The current task and the decision under investigation.
+2. What the evidence establishes, with its source.
+3. The working explanation and plausible alternatives.
+4. Relevant exceptions, dependencies or technical risks actually observed.
+5. Missing evidence and the next check that would change the decision.
+
+Do not fill a quota of risks, exceptions or questions. If no system was inspected, do not invent code findings. If several interpretations have failed, reassess the evidence and investigation method rather than blaming the person who wrote the brief.
+
+For a bound engagement, propose updates to the existing records after the discovery result is reviewed:
+
+- `reality.md`: preserve `Working theory`, `Evidence` and `Differs from brief how`; add the decision frame and validation status.
+- `terrain.md`: relevant steps, system behavior, data dependencies and unknowns. Preserve the `## Operating map (exception-led)` section and its columns when recording observed breaks.
+- `assumptions.md`: new or changed assumptions, verification owners and checkpoints.
+
+An operating-map row uses: `Exception / break | Who notices first | What they do today | System of record then | Blast | Evidence`. Preserve the existing schema. If no break has been observed, report that gap; do not fabricate a row to satisfy a readiness check.
+
+For standalone work, return the same findings in the conversation or requested document. No `.fde/` write or initialization is needed.
+
+## Worked example
+
+This example is fictional and uses only supplied meeting notes.
+
+The brief asks for an assistant to draft responses. The supplied notes say drafting takes about four minutes, while requests sometimes wait a day for assignment. The timings come from a team lead; no measured baseline is available.
+
+**Working theory:** assignment delay may matter more than drafting time. **Evidence:** the lead's estimates in the supplied notes, still unverified. **Differs from brief how:** the requested assistant addresses drafting, while the reported delay concerns assignment. **Question:** what causes the assignment delay, and which change would reduce it? **Next check:** trace a sample of recent requests using arrival and assignment timestamps, then ask the people handling delayed cases what prevented assignment.
+
+The discovery result does not reject the assistant or declare an ownership problem solved. It gives the FDE a focused way to find out what to build, change or investigate next. Return this as a short draft for notes-only work; in a bound engagement, propose it for `reality.md` with validation still pending.
+
+## Principles
+
+- Investigate the work before choosing a solution.
+- Keep observations, estimates and hypotheses distinct.
+- Match discovery effort to the decision at hand.
+- Unknown ownership and missing evidence remain explicit.
+- Confirmation comes from the responsible person, never from silence.