fdeops 4.0.3 → 4.1.0

package/AGENTS.md

@@ -8,7 +8,7 @@ Route via **`@fde`** - read `skills/fde/SKILL.md` (the single source of truth),
 
 ## If you are contributing to this repository
 
-- **One brain.** Method lives once in `skills/fde/SKILL.md` + `skills/fde/references/`. Adapters in `adapters/` only point at it - never fork logic per platform.
+- **One brain.** Method lives once in `skills/fde/SKILL.md` + `skills/fde/references/`. Adapters in `adapters/` only point at it - never fork logic per platform. Standalone skills are generated by `node bin/generate-skills.js` from `bin/skill-catalog.js` and canonical references; do not hand-edit generated copies.
 - **Deterministic core.** `bin/fde.js` is local-only (git + file reads, no network, no AI). Keep it that way.
 - **Run the checks.** `npm run check` must pass before any PR (`node bin/check.js`).
 - **Conventions.** See `CONTRIBUTING.md`, `docs/REPO_LAYOUT.md`, and `docs/schema.md`.

package/README.md

@@ -4,18 +4,41 @@
 
 <a name="why-use-it"></a>
 
-You're on a customer site. The AI coding agent writes code in their repo. This kit is the work around that code: the brief, who can say yes, proof on their staging then live, whether they signed off, whether they can run it after you leave.
+Take a customer request from discovery through implementation, verification and handoff. Use one task skill for the work in front of you, or `@fde` to coordinate the engagement and keep its decisions and evidence together.
 
 Notes stay on your laptop, in a separate record for each client. Review the agent's proposed changes before saving them.
 
-Keep the coding pack you already use. FDEOps adds the client brief, decisions, and evidence around that work.
+Implementation, integration, debugging and QA are included. Use your existing repository tools; no additional skill pack is required. Credentials, infrastructure and production authority still come from the customer.
 
-[Quick start](#quick-start) · [Daily fieldbook](#your-daily-fieldbook) · [30 skills](#all-30-skills) · [Documentation](docs/README.md)
+[Quick start](#quick-start) · [Daily fieldbook](#your-daily-fieldbook) · [Task skills](#task-skills) · [Documentation](docs/README.md)
 
 <img width="960" height="640" alt="FDEOps: client delivery from the first meeting to handover" src="https://github.com/user-attachments/assets/2bcb8739-55ee-445d-8a1a-8b38433b7b58" />
 
 ---
 
+## Task skills
+
+Call the task directly when you know what you need. No client folder is required for a one-off task.
+
+| Work | Skill |
+|------|-------|
+| Understand the workflow | `fde-discover` |
+| Handle a new scope request | `fde-scope` |
+| Compare approaches | `fde-options` |
+| Test a risky assumption | `fde-poc` |
+| Implement, integrate, repair | `fde-build`, `fde-integrate`, `fde-debug` |
+| Review, evaluate AI, test the journey | `fde-review`, `fde-evaluate`, `fde-qa` |
+| Release a verified increment | `fde-ship` |
+| Present evidence, transfer operation, reuse a lesson | `fde-readout`, `fde-handoff`, `fde-feedback` |
+
+For example, install just the integration skill:
+
+```bash
+npx skills add suboss87/fdeops --skill fde-integrate
+```
+
+Ask it to connect a permitted customer API and test retry behavior. It includes the references it needs. `@fde` uses those same methods when the integration is part of an ongoing engagement. [Full pack and selective installation](docs/install.md#individual-skills-and-the-full-pack).
+
 ## Quick Start
 
 **Try it in a local checkout.** Requires Node.js 18+ and Git:
@@ -138,9 +161,9 @@ You can also just say it: “Prep me for the sponsor meeting,” “What did we
 
 ---
 
-## All 30 Skills
+## Engagement workflows
 
-Thirty situations, grouped by stage. Each skill gives the agent steps to follow, a record or report to produce, and a checkpoint with you. You describe the work; `@fde` finds the skill.
+Thirty-four workflows, grouped by stage. Each skill gives the agent steps to follow, a record or report to produce, and a checkpoint with you. You describe the work; `@fde` finds the skill.
 
 Full detail: [docs/skills-reference.md](docs/skills-reference.md).
 
@@ -176,7 +199,11 @@ Full detail: [docs/skills-reference.md](docs/skills-reference.md).
 
 | Skill | What it does | Use when |
 |--------|--------------|----------|
-| [ship](skills/fde/references/ship.md) | Deliver the increment | Building, updating, or going live |
+| [build](skills/fde/references/build.md) | Implement the increment | A scoped change in their repository |
+| [integrate](skills/fde/references/integrate.md) | Prove the system boundary | APIs, imports and write-back |
+| [debug](skills/fde/references/debug.md) | Reproduce and repair a failure | Unexpected behavior or a regression |
+| [qa](skills/fde/references/qa.md) | Exercise the delivered journey | Functional acceptance or browser QA |
+| [ship](skills/fde/references/ship.md) | Release with evidence | Ready for an authorized rollout |
 | [what-breaks](skills/fde/references/what-breaks.md) | Assess impact | Touching shared infrastructure |
 | [rescue](skills/fde/references/rescue.md) | Resolve the incident | Down, or they went quiet |
 | [review](skills/fde/references/review.md) | Review the change | Before merge, scope creep |

package/bin/check.js

@@ -6,6 +6,7 @@ const fs = require('fs')
 const path = require('path')
 
 const root = path.join(__dirname, '..')
+const catalog = require('./skill-catalog')
 let failed = 0
 
 function fail(msg) {
@@ -190,8 +191,8 @@ ok(`router dispatch (${mentioned.length} reference targets verified) + memory co
     // 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+skills/g)].map(m => Number(m[1]))
-    if (!claims.length) fail(`${rel} must state how many skills it documents`)
+    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`)
@@ -204,20 +205,10 @@ ok(`router dispatch (${mentioned.length} reference targets verified) + memory co
   if (extra.length) fail(`unrouted reference file(s) - dead skill: ${extra.join(', ')}`)
   else ok('no unrouted reference files')
 
-  // The on-site change loop lives in ship.md. A sibling skill is a split.
-  for (const dead of ['small-prs.md', 'thin-slices.md', 'implement.md']) {
-    if (fs.existsSync(path.join(refDir, dead))) {
-      fail(`${dead} must not exist - that craft lives in ship.md`)
-    }
-  }
-  ok('ship is one skill (no implement / small-prs / thin-slices sibling)')
-
   if (/^### Prove\b/m.test(read('skills/fde/SKILL.md'))) {
     fail('SKILL.md must not use Prove as a stage heading - the public stage is Outcome')
   } else ok('SKILL.md stage heading is Outcome')
-  if (/\b31 names\b|\b31 skills\b/.test(read('README.md'))) {
-    fail('README must not advertise 31 skills')
-  } else ok('README skill count is 30')
+
 }
 
 const install = read('bin/install.js')
@@ -292,11 +283,11 @@ if (!readme.includes('fde-engagements') || !/fdeops.*resume --init/i.test(readme
 // The advertised command must name the one skill a field user wants.
 // Contributor CLI attack notes live in evals/testing-fieldbook.md, not as a skill.
 for (const m of readme.match(/^.*npx skills add .*$/gm) || []) {
-  if (!m.includes('--skill fde')) {
-    fail(`README skills-add command must pin --skill fde: ${m.trim()}`)
+  if (!['fde', ...catalog.map(s => s.name)].some(name => new RegExp(`--skill ${name}(?:\\s|$)`).test(m))) {
+    fail(`README skills-add command must name a shipped skill: ${m.trim()}`)
   }
 }
-ok('README skills install is one skill')
+ok('README skill install commands name a discoverable entry')
 
 // A skill-only install has no fde on the PATH; the router must reach npx before
 // falling back to writing memory by hand.
@@ -661,9 +652,10 @@ for (const entry of fs.readdirSync(path.join(root, 'skills'))) {
     ok(`skill ${entry} discoverable`)
   }
 }
-if (skillDirs.length !== 1 || skillDirs[0] !== 'fde') {
-  fail(`public tree ships one skill (skills/fde); found: ${skillDirs.join(', ') || '(none)'}`)
-} else ok('one public skill')
+const expectedSkills = ['fde', ...catalog.map(s => s.name)].sort()
+if (JSON.stringify(skillDirs.sort()) !== JSON.stringify(expectedSkills)) fail('Skill directories differ from catalog')
+try { require('./generate-skills').generate(true); ok('generated standalone reference closure and freshness') }
+catch (error) { fail(error.message) }
 
 function findSkillMd(dir, acc = []) {
   for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -675,10 +667,9 @@ function findSkillMd(dir, acc = []) {
   return acc
 }
 const skillFiles = findSkillMd(root)
-const allowedSkill = path.join('skills', 'fde', 'SKILL.md')
-if (skillFiles.length !== 1 || skillFiles[0] !== allowedSkill) {
-  fail(`only ${allowedSkill} may exist; found: ${skillFiles.join(', ') || '(none)'}`)
-} else ok('one SKILL.md')
+const allowedSkills = expectedSkills.map(name => path.join('skills', name, 'SKILL.md')).sort()
+if (JSON.stringify(skillFiles.sort()) !== JSON.stringify(allowedSkills)) fail('Unexpected SKILL.md outside public catalog')
+else ok('all skill entry points accounted for')
 
 if (!fs.existsSync(path.join(root, '.github', 'ISSUE_TEMPLATE', 'bug_report.yml'))) {
   fail('GitHub issue template missing')

package/bin/fde.js

@@ -36,7 +36,7 @@ const { createMemoryApi } = require('./lib/memory')
 const { createTrustApi } = require('./lib/trust')
 const vault = require('./lib/vault')
 const context = require('./lib/context')
-const { sourceReference, hasSource, datedDecisions } = require('./lib/provenance')
+const { sourceReference, sourceReferences, hasSource, datedDecisions } = require('./lib/provenance')
 const { deliverySummary } = require('./lib/delivery-gaps')
 
 const HOME = os.homedir()
@@ -67,8 +67,13 @@ function maskReport(value) {
   if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, maskReport(item)]))
   return value
 }
-function maskedSections(sections, maxBytes) {
-  return context.boundedSections(sections.map(text => masking.mask(text)), maxBytes)
+function maskedSections(sections, maxBytes = context.DEFAULT_BYTES, heading = '') {
+  // Reserve identity before sharing the remaining budget between excerpts.
+  // Pathological path lengths remain explicitly clipped rather than exhausting policy space.
+  const maskedHeading = masking.mask(heading)
+  const prefix = heading ? (Buffer.byteLength(maskedHeading) <= 1024 ? maskedHeading
+    : context.clipMaskedUtf8(maskedHeading, 900) + '\n[Identity path truncated; use fde resume --bind to inspect.]') + '\n\n' : ''
+  return prefix + context.boundedSections(sections.map(text => masking.mask(text)), maxBytes - Buffer.byteLength(prefix))
 }
 const DEBRIEF_MAX_BYTES = 256 * 1024
 const CODE_EXT = ['.js', '.ts', '.tsx', '.jsx', '.py', '.java', '.go', '.rb', '.cs', '.php']
@@ -1459,12 +1464,12 @@ function cmdResume(args) {
   process.stdout.write(maskedSections([
     policy ? `CLIENT POLICY - trust-profile.md\n${policy}` : '',
     preferences.work ? `WORKING PREFERENCES: ${preferences.work}. Starting help: ${preferences.start}.\n${setup.nextStep(preferences)}\nThis is a starting preference, not a client fact; current instructions and engagement state take precedence.` : '',
-    `${intro}\n\nENGAGEMENT: ${eng}`,
+    intro,
     success ? `CURRENT GOALS & ACCEPTANCE - success.md\n${success}` : '',
     risks ? `OPEN RISKS - risks.md\n${extractRisks(eng).map(r => r.text).join('\n') || '(none recorded)'}` : '',
     `VALUE LEDGER - delivery.md\n${parseValueLedger(eng).rows.map(r => formatValueLedgerLine(r) + '; source: ' + (r.evidence || '(missing)')).join('\n') || '(none recorded)'}`,
     `WORKING CONTEXT - context.md\n${ctx ? resumeView(ctx) : '(no context.md yet)'}`,
-  ], maxBytes))
+  ], maxBytes, `ENGAGEMENT: ${eng}`))
 }
 
 // Token discipline: context.md grows every session (the session-stop hook
@@ -2083,7 +2088,10 @@ function withDebriefRecords(eng, apply, files = ['decisions.md', 'risks.md', 'de
         } catch (_) { failed.push(path.basename(target)) }
       }
       if (failed.length) throw new Error(`${error.message}; recovery could not restore ${failed.join(', ')}. Inspect these records and the pending proposal before retrying.`)
-      throw new Error(`${error.message}; no record changes kept. The proposal is retained; retry after resolving the cause.`)
+      const recovery = snapshots.get(path.join(eng, DEBRIEF_PROPOSE))
+        ? 'The proposal is retained; inspect it with fde debrief --review before retrying.'
+        : 'No pending proposal was retained; review your input before retrying.'
+      throw new Error(`${error.message}; no record changes kept. ${recovery}`)
     } finally { debriefTransactionActive = false }
   }
   return lockAt(0)
@@ -2156,7 +2164,7 @@ function routeDebriefInput(eng, input, { dry, force, sealed = [], allowReplay =
     })
   }
   const repeats = repeatedDebriefStatements(eng, input)
-  if (repeats.length && !dry && !allowReplay) throw new Error('source-backed statement already recorded; review the existing record and newer next action. Explicitly confirm a repeat with --allow-replay, or remove the repeated statement from the proposal.')
+  if (repeats.length && !dry && !allowReplay) throw new Error('source-backed statement already recorded; review the existing record and newer next action. Explicitly confirm a repeat with --allow-replay, or remove the repeated statement from your input or pending proposal.')
   const d = new Date()
   const date = d.toISOString().slice(0, 10)
   const counts = { decision: 0, risk: 0, delivery: 0, contact: 0, next: 0, signer: 0 }
@@ -2547,15 +2555,20 @@ function cmdReceipts(args) {
   const records = [], claims = []
   for (const file of [...recordFiles, ...workingFiles]) {
     const document = readClean(eng, file)
+    const scaffold = new Set((templatesDir() ? readClean(templatesDir(), file) : '').split('\n').map(line => line.trim()))
     const decisionSources = new Map()
     if (file === 'decisions.md') for (const entry of datedDecisions(document)) {
-      const source = sourceReference(entry.text)
-      for (let line = entry.line; line < entry.line + entry.text.split('\n').length; line++) decisionSources.set(line, source)
+      for (let line = entry.line; line < entry.line + entry.text.split('\n').length; line++) decisionSources.set(line, entry.text)
     }
     document.split('\n').forEach((line, i) => {
       if (!line.toLowerCase().includes(term.toLowerCase())) return
-      const source = decisionSources.get(i + 1) || sourceReference(line)
-      const hit = `  ${file}:${i + 1}  ${masking.mask(line.trim()).slice(0, 160)}${source ? ` [source: ${masking.mask(source).slice(0, 160)}]` : ' [source missing]'}${dirty.has(file) ? '  dirty file - review manual edits' : ''}`
+      const sourceText = decisionSources.get(i + 1) || line
+      const source = sourceReference(sourceText)
+      if (!source && scaffold.has(line.trim())) return
+      const sources = sourceReferences(sourceText)
+      const attribution = masking.mask(sources.join('; '))
+      const displayed = Buffer.byteLength(attribution) <= 320 ? attribution : context.clipMaskedUtf8(attribution, 240) + '… [sources truncated; use fde recall]'
+      const hit = `  ${file}:${i + 1}  ${context.clipMaskedUtf8(masking.mask(line.trim()), 160)}${source ? ` [${sources.length > 1 ? 'sources' : 'source'}: ${displayed}]` : ' [source missing]'}${dirty.has(file) ? '  dirty file - review manual edits' : ''}`
       ;(recordFiles.includes(file) && source ? records : claims).push({ file, hit })
     })
   }

package/bin/generate-skills.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Generated packages are independent installations, not independently authored methods.
+const fs = require('node:fs')
+const path = require('node:path')
+const catalog = require('./skill-catalog')
+const root = path.resolve(__dirname, '..')
+const source = path.join(root, 'skills/fde/references')
+
+function referencesFor(method, referenceRoot = source) {
+  const known = new Set(fs.readdirSync(referenceRoot).filter(f => f.endsWith('.md')))
+  const pending = [`${method}.md`, 'task-context.md']
+  const found = new Set()
+  while (pending.length) {
+    const file = pending.pop()
+    if (found.has(file)) continue
+    if (!known.has(file)) throw new Error(`Missing canonical reference: ${file}`)
+    found.add(file)
+    const body = fs.readFileSync(path.join(referenceRoot, file), 'utf8')
+    // Includes plain/backticked method links in older references as well as Markdown links.
+    for (const match of body.matchAll(/(?<![\w-])([a-z][a-z-]*\.md)\b/g)) {
+      if (known.has(match[1]) && !found.has(match[1])) pending.push(match[1])
+    }
+    for (const match of body.matchAll(/\]\(([^)]+\.md)(?:#[^)]*)?\)/g)) {
+      if (/^(?:https?:|#)/.test(match[1])) continue
+      const target = path.resolve(referenceRoot, match[1])
+      if (path.dirname(target) !== referenceRoot || !known.has(path.basename(target))) {
+        throw new Error(`Nonportable instruction link in ${file}: ${match[1]}`)
+      }
+    }
+  }
+  return [...found].sort()
+}
+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`
+}
+function expectedFiles(item, referenceRoot = source) {
+  const files = new Map([['SKILL.md', entrypoint(item)]])
+  for (const ref of referencesFor(item.method, referenceRoot)) files.set(`references/${ref}`, fs.readFileSync(path.join(referenceRoot, ref), 'utf8'))
+  return files
+}
+function walk(dir, prefix = '') {
+  if (!fs.existsSync(dir)) return []
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap(e => {
+    if (e.isSymbolicLink()) throw new Error(`Unexpected symlink: ${path.join(dir, e.name)}`)
+    const rel = prefix + e.name
+    return e.isDirectory() ? walk(path.join(dir, e.name), rel + '/') : [rel]
+  })
+}
+function generate(check = false) {
+  const errors = []
+  for (const item of catalog) {
+    const dest = path.join(root, 'skills', item.name)
+    const expected = expectedFiles(item)
+    for (const rel of walk(dest)) if (!expected.has(rel)) errors.push(`Unexpected generated file: ${item.name}/${rel}`)
+    for (const [rel, body] of expected) {
+      const target = path.join(dest, rel)
+      if (check) {
+        if (!fs.existsSync(target) || fs.readFileSync(target, 'utf8') !== body) errors.push(`Stale generated skill: ${item.name}/${rel}`)
+      } else {
+        fs.mkdirSync(path.dirname(target), { recursive: true })
+        fs.writeFileSync(target, body)
+      }
+    }
+  }
+  if (errors.length) throw new Error(errors.join('\n'))
+}
+module.exports = { referencesFor, expectedFiles, generate }
+if (require.main === module) {
+  try { generate(process.argv.includes('--check')); console.log('Skill packages match canonical methods.') }
+  catch (error) { console.error(error.message); process.exitCode = 1 }
+}

package/bin/install.js

@@ -100,7 +100,7 @@ function wasInstalledByUs(dir) {
   } catch (_) { return false }
 }
 
-// v2 shipped 16 standalone skills; v3 is one `fde` skill + references.
+// Retire v2 entries only when the current pack does not ship their replacement.
 // Leaving the old ones in place would route users to stale content.
 const LEGACY_SKILL_DIRS = [
   'fde-land', 'fde-discover', 'fde-audit', 'fde-rescue', 'fde-sketch',
@@ -115,6 +115,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
     const p = path.join(GLOBAL_SKILLS_DIR, dir)
     if (isLink(p)) { links.push(dir); continue }
     if (!fs.existsSync(path.join(p, 'SKILL.md'))) continue

package/bin/lib/context.js

@@ -14,6 +14,13 @@ function clipUtf8(text, bytes) {
   while (end > 0 && (buf[end] & 0xc0) === 0x80) end--
   return buf.subarray(0, end).toString('utf8')
 }
+// Masking aliases must stay whole so they remain recognizable and reversible.
+function clipMaskedUtf8(text, bytes) {
+  const clipped = clipUtf8(text, bytes)
+  if (clipped === text) return text
+  const open = clipped.lastIndexOf('[[')
+  return open > clipped.lastIndexOf(']]') ? clipped.slice(0, open) : clipped
+}
 function budgetArgs(args, defaultBytes = DEFAULT_BYTES) {
   const rest = [...args]
   let maxBytes = defaultBytes
@@ -91,4 +98,4 @@ function recallSections(documents, query, maxHits = 12, outputText = text => tex
     sections: selected.map(h => `${h.file}:${h.line}-${h.end} (lines in redacted view)\n${h.text}`),
   }
 }
-module.exports = { DEFAULT_BYTES, clipUtf8, budgetArgs, boundedSections, recallSections }
+module.exports = { DEFAULT_BYTES, clipUtf8, clipMaskedUtf8, budgetArgs, boundedSections, recallSections }

package/bin/lib/provenance.js

@@ -40,3 +40,13 @@ function datedDecisions(value) {
   return entries.sort((a, b) => a.date.localeCompare(b.date) || a.line - b.line)
 }
 module.exports.datedDecisions = datedDecisions
+
+// Display every explicit attribution without selecting a primary source.
+// Keep classification through sourceReference unchanged.
+function sourceReferences(value) {
+  const explicit = String(value || '').match(/\[source:[^\]\n]+\]/gi) || []
+  if (explicit.length) return [...new Set(explicit.map(sourceReference).filter(Boolean))]
+  const fallback = sourceReference(value)
+  return fallback ? [fallback] : []
+}
+module.exports.sourceReferences = sourceReferences

package/bin/skill-catalog.js

@@ -0,0 +1,17 @@
+// Public entry points. Methods remain authored once in skills/fde/references/.
+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 }))

package/mcp/fdeops-ingest/package.json

@@ -1,8 +1,8 @@
 {
   "name": "fdeops-ingest-mcp",
-  "version": "4.0.3",
+  "version": "4.1.0",
   "private": true,
-  "description": "Thin stdio MCP sink for FDEOps ingest (stage → propose → apply). Zero runtime dependencies.",
+  "description": "Thin stdio MCP sink for FDEOps ingest (stage \u2192 propose \u2192 apply). Zero runtime dependencies.",
   "bin": {
     "fdeops-ingest-mcp": "./server.js"
   },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fdeops",
-  "version": "4.0.3",
-  "description": "Client delivery tools for Forward Deployed Engineers. One @fde skill, local Markdown engagement records, and an offline dashboard for decisions, evidence, approvals, and next actions.",
+  "version": "4.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",
     "fde": "bin/fde.js"
@@ -10,7 +10,8 @@
     "check": "node bin/check.js && npm test",
     "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"
+    "prepublishOnly": "node bin/check.js && npm test",
+    "generate:skills": "node bin/generate-skills.js"
   },
   "files": [
     "bin/",

package/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "fdeops",
-  "version": "4.0.3",
-  "description": "Forward deployed engineering skills for AI coding agents. One @fde skill for the client work around the code. You confirm; then it lands in .fde/ on your laptop.",
+  "version": "4.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",
     "url": "https://github.com/suboss87"

package/skills/fde/SKILL.md

@@ -7,7 +7,11 @@ description: Keeps the engagement record for client work. Use when they name a c
 
 ## Purpose
 
-The **engagement record** for one client, from first meeting to signed outcome. One skill; six stages (land → close). Same map at any scale, on greenfield or brownfield, in any industry (overlays). You route; they never pick a skill. Confirm, then write `.fde/`. The workspace still compiles and commits. `@fde` does not leave.
+The **engagement record** for one client, from first meeting to signed outcome. One coordinator; six stages (land → close), with task skills that also work independently. Same methods on greenfield or brownfield engagements. Route from the request; never make the user choose a phase. Confirm, then write `.fde/`. The workspace still compiles and commits. `@fde` does not leave.
+
+## Task entry
+
+Read `references/task-context.md` first. An explicitly selected `fde-*` task runs directly; do not wrap it in another coordinator or repeat entry. For a one-off task with supplied context, use the relevant method without initializing `.fde/`. For ongoing client work use the bounded entry and memory contract below. Missing record files alone are not a reason to restart discovery.
 
 ## When to use
 
@@ -42,15 +46,15 @@ On someone else's site the work is not "write code, remember later." Every chang
 
 Scale the loop to the change. A routine, reversible fix within confirmed scope reuses the existing outcome, signer, acceptance criteria, and engineering plan; batch its verification into a concise delivery receipt. It does not need a new sponsor decision or staging ceremony per edit. New outcomes, changed acceptance or authority, and production release decisions still need the relevant confirmation and evidence. This does not bypass confirmation for judgment written into the engagement record.
 
-**Status is explicit.** Record what is implemented, verified, deployed, and accepted separately. A routine fix may be implementation-complete before release or customer acceptance; state what remains and attach the current verification receipt. A coding pack may write the function; `@fde` owns the engagement evidence.
+**Status is explicit.** Record what is implemented, verified, deployed, and accepted separately. A routine fix may be implementation-complete before release or customer acceptance; state what remains and attach the current verification receipt. The included build, integrate, debug and QA methods cover implementation; `@fde` connects their evidence to the engagement.
 
-## Working with an engineering pack
+## Engineering within the pack
 
-Use the customer's existing coding, testing, review, and repository instructions for implementation. Carry the confirmed outcome, scope boundary, acceptance criteria, and evidence requirements into that workflow. Reference its existing plan from `decisions.md`; do not create a competing backlog or repeat questions already answered. FDEOps owns the engagement record and acceptance status. A coding pack's green tests do not establish customer acceptance. Never claim compatibility was tested with a host or pack you have not run.
+Use `references/build.md` for implementation, `references/integrate.md` for customer-system boundaries, `references/debug.md` for failures and `references/qa.md` for the delivered journey. Each uses `references/verification.md` for actual evidence. These methods use the customer's coding conventions and installed tools; another skill pack is not required. Use an existing engineering plan rather than creating a competing backlog. Green tests establish tested behavior, not customer acceptance or production authority.
 
 ## Human surface vs agent plumbing
 
-**FDE (human):** `@fde` + English, or `/brief` `/discover` `/plan` `/ship` `/outcome` `/close` `/debrief` `/prep` `/trust` `/receipts` `/readout`. Never a skill catalog.
+**FDE (human):** `@fde` + English, or `/brief` `/discover` `/plan` `/ship` `/outcome` `/close` `/debrief` `/prep` `/trust` `/receipts` `/readout`. They may also invoke an individual `fde-*` skill directly.
 
 **You (agent):** run the CLI. **Never tell the FDE to type** `fde …`. If unbound, you run `fde resume --init` after one question. Never ask them to run the CLI.
 
@@ -91,7 +95,7 @@ Writes need a bind (`FDEOPS_ENGAGEMENT` or registry). Never install fdeops on in
 ## The memory contract
 
 1. **On entry:** follow **Entry (every session)** above for the current packet and refresh rules. Retrieve additional evidence through targeted `fde recall` when needed.
-2. **Deliverable = memory.** The work *is* the `.fde/` file. The reference names which one.
+2. **Deliverable plus memory.** Deliver the requested code, evidence or decision artifact. On a bound engagement, record the confirmed result in the file named by the method. A standalone artifact does not require a `.fde/` folder.
 3. **Evidence.** Without a supplied source, a decision or measurement remains CLAIM. Use `[source: meeting YYYY-MM-DD]`, a PR/URL, transcript ID, or artifact path. The automatic log date is not attribution. ON RECORD means a source was supplied, not that it was authenticated or the customer approved. Never invent a source, signer, or acceptance.
 4. **No invented facts.** People, quotes, meetings, numbers: they said it or the repo shows it. Else `unknown - ask: <question>`.
 5. **Session digest** (end of session and before a PR) - thinking, not the chat. Confirm, then write. Never a transcript dump.
@@ -162,7 +166,11 @@ Work names (engage, diagnose, align, deliver, realize, transfer) are the same ma
 |----------|-------|-----------|
 | What could go wrong, touching shared infrastructure, need to assess impact, assess impact, provision, IaC, shared infra | what-breaks | `references/what-breaks.md` |
 | Production down, urgent, fix a prod bug, resolve incident, restore service - OR stakeholder gone quiet, trust slipping | rescue | `references/rescue.md` |
-| Deliver, start building, update their checkout, first module, visible progress, their tests, POC follow-through, ready to deploy, going live, pre-flight, deliver the increment, build the increment, create the launch plan, design their UI | ship | `references/ship.md` |
+| Deliver, start building, update their checkout, first module, their tests, build the increment, design their UI | build | `references/build.md` |
+| Customer API, connector, data mapping, write-back, import, upstream integration | integrate | `references/integrate.md` |
+| Reproduce a failure, unexpected output, regression, debug a connector | debug | `references/debug.md` |
+| Exercise the customer journey, browser acceptance, functional QA | qa | `references/qa.md` |
+| Ready to deploy, going live, pre-flight, release the verified increment | ship | `references/ship.md` |
 | Review this change, review the pull request, is it safe, does it match what we agreed | review | `references/review.md` |
 | Diff grew / scope creep in the PR / "did we only build what we said" / KEEP JUSTIFY SPLIT DROP | review (+ ship if going live) | `references/review.md` Stage 1 · `references/ship.md` Intent vs diff |
 | Wrap the session / share the thinking / catch teammates up / before I open the PR | (memory contract - session digest) | SKILL.md **Session digest** - write TL;DR + decisions/why into `.fde/`; no transcript sync |
@@ -203,17 +211,17 @@ Work names (engage, diagnose, align, deliver, realize, transfer) are the same ma
 | Payments, cardholder data, PCI-DSS, anything that moves money | `references/fintech.md` |
 | Government agency, FedRAMP, ATO, CUI, classified | `references/gov.md` |
 
-Ready to build with no `terrain.md` / plan: discover or plan first. Takeover without `audit.md`: audit first. Two customers in one message: confirm which folder.
+Ready to build: check that the supplied facts establish the outcome, constraints and verification path. Use discover or plan only for material gaps. On a takeover, audit inherited claims that affect the task. Two customers in one message: confirm which folder.
 
 ## Principles
 
 - Never ask the FDE to pick a phase. That's your job.
 - Same six stages at any scale. Overlays carry the industry. Greenfield and brownfield change the first move inside ship, not the map.
-- Ground loop on a bound client: name → characterise → verify in the agreed environment → authorize release → log. A coding pack may write the function. `@fde` still owns done. When they disagree, their repo and the signer win.
+- Ground loop on a bound client: name → characterise → verify in the agreed environment → authorize release → log. The included engineering methods do the build. `@fde` keeps delivery status explicit. When they disagree, their repo and the signer win.
 - Customer delivery needs a replayable acceptance check in the agreed environment; reuse existing criteria for routine fixes. Missing evidence means unproven, not an observed test failure. Never equate implementation-complete with deployed or customer-accepted.
 - Read the current entry packet before speaking; follow **Entry (every session)** above. One sharp question - never a barrage.
 - Never invent people, meetings, or numbers - `unknown - ask:` beats a polished lie.
-- Every phase ends with its artifact written. No artifact, no "done."
+- Deliver the task artifact; persist confirmed engagement judgments only when bound. Never manufacture a record to satisfy a checklist.
 - Evidence on every claim. The FDE will be challenged on these files.
 - Overlays activate on signal, not on request.
 - Load `.fde/` files on demand, never the whole folder.

package/skills/fde/references/board-memo.md

@@ -12,7 +12,7 @@ Technical FDEs lose renewals by presenting work instead of outcomes. The exec do
 
 ```
 GOVERNING THOUGHT: (one sentence - the conclusion)
-"The payment processing overhaul cut manual reconciliation from 
+"The payment processing overhaul cut manual reconciliation from
 3 FTEs to 0.5 FTE and eliminated the $2M annual audit risk."
 
 SUPPORT 1: What was done (one paragraph)

package/skills/fde/references/build.md

@@ -0,0 +1,20 @@
+# 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).
+
+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.
+
+## Method
+
+1. Identify the repository, its instructions, working tree, relevant callers, and test commands. Inspect examples before creating abstractions. Preserve unrelated edits and state which dependencies or interfaces the change touches.
+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.
+5. 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. 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.
+
+## Deliverable and 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.
+
+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.