fdeops 4.0.4 → 4.1.1

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/generate-skills.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// Generated packages are independent installations, not independently authored methods.
+const fs = require('node:fs')
+const path = require('node:path')
+const { createHash } = require('node:crypto')
+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
+}
+const marker = '<!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->'
+const manifestName = '.fde-generated.json'
+const digest = body => createHash('sha256').update(body).digest('hex')
+const stat = file => {
+  try { return fs.lstatSync(file) } catch (error) { if (error.code === 'ENOENT') return null; throw error }
+}
+function walk(dir, prefix = '') {
+  const entries = []
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const rel = prefix + e.name
+    if (e.isSymbolicLink() || (!e.isDirectory() && !e.isFile()) || (e.isFile() && fs.lstatSync(path.join(dir, e.name)).nlink > 1)) throw new Error(`Unsafe generated path: ${path.join(dir, e.name)}`)
+    if (e.isDirectory()) {
+      if (rel !== 'references') throw new Error(`Unowned generated directory: ${path.join(dir, e.name)}`)
+      entries.push(...walk(path.join(dir, e.name), rel + '/'))
+    } else entries.push(rel)
+  }
+  return entries
+}
+function generate(check = false, options = {}) {
+  const skillRoot = path.join(options.root || root, 'skills')
+  const referenceRoot = options.referenceRoot || source
+  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}`)
+    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 errors = []
+  const plans = []
+  for (const name of names) {
+    const dest = path.join(skillRoot, name)
+    const expected = wanted.get(name) || new Map()
+    const destStat = stat(dest)
+    let owned = {}
+    let actual = []
+    if (destStat) {
+      if (!destStat.isDirectory() || destStat.isSymbolicLink()) {
+        if (wanted.has(name)) throw new Error(`Unsafe generated path: ${dest}`)
+        continue
+      }
+      const entry = path.join(dest, 'SKILL.md')
+      const entryStat = stat(entry)
+      const isGenerated = entryStat && entryStat.isFile() && fs.readFileSync(entry, 'utf8').includes(marker)
+      if (!isGenerated) {
+        if (wanted.has(name) || stat(path.join(dest, manifestName))) throw new Error(`Unowned skill: ${name}`)
+        continue
+      }
+      actual = walk(dest)
+      if (actual.includes(manifestName)) {
+        const manifest = JSON.parse(fs.readFileSync(path.join(dest, manifestName), 'utf8'))
+        if (manifest.generator !== 'bin/generate-skills.js' || manifest.version !== 1 || !manifest.files || Array.isArray(manifest.files) || typeof manifest.files !== 'object') throw new Error(`Invalid ownership manifest: ${name}`)
+        owned = manifest.files
+        for (const [rel, hash] of Object.entries(owned)) {
+          if (!/^(?:SKILL\.md|references\/[a-z][a-z-]*\.md)$/.test(rel) || !/^[a-f0-9]{64}$/.test(hash)) throw new Error(`Invalid ownership entry: ${name}/${rel}`)
+        }
+      } else {
+        // Migrate 4.1.0 packages conservatively: only the marked entry and exact
+        // canonical copies are known to belong to the generator.
+        for (const rel of actual) {
+          const body = fs.readFileSync(path.join(dest, rel))
+          const canonical = path.join(referenceRoot, path.basename(rel))
+          if (rel === 'SKILL.md' || (/^references\/[a-z][a-z-]*\.md$/.test(rel) && stat(canonical)?.isFile() && body.equals(fs.readFileSync(canonical)))) owned[rel] = digest(body)
+        }
+      }
+      for (const rel of actual.filter(rel => rel !== manifestName)) {
+        if (!Object.hasOwn(owned, rel)) throw new Error(`Unowned generated file: ${name}/${rel}`)
+        if (!expected.has(rel) && digest(fs.readFileSync(path.join(dest, rel))) !== owned[rel]) throw new Error(`Modified obsolete generated file: ${name}/${rel}`)
+      }
+    }
+    const output = new Map(expected)
+    if (wanted.has(name)) output.set(manifestName, JSON.stringify({ generator: 'bin/generate-skills.js', version: 1, files: Object.fromEntries([...expected].map(([rel, body]) => [rel, digest(body)])) }, null, 2) + '\n')
+    for (const rel of actual) if (!output.has(rel)) errors.push(`Obsolete generated file: ${name}/${rel}`)
+    for (const [rel, body] of output) {
+      if (!actual.includes(rel) || fs.readFileSync(path.join(dest, rel), 'utf8') !== body) errors.push(`Stale generated skill: ${name}/${rel}`)
+    }
+    plans.push({ dest, actual, output })
+  }
+  if (check) {
+    if (errors.length) throw new Error(errors.join('\n'))
+    return
+  }
+  // All ownership and path checks finish before any package is changed.
+  for (const { dest, actual, output } of plans) {
+    for (const rel of actual) if (!output.has(rel)) fs.unlinkSync(path.join(dest, rel))
+    for (const [rel, body] of output) {
+      fs.mkdirSync(path.dirname(path.join(dest, rel)), { recursive: true })
+      fs.writeFileSync(path.join(dest, rel), body)
+    }
+    if (!output.size) {
+      const refs = path.join(dest, 'references')
+      if (stat(refs)) fs.rmdirSync(refs)
+      fs.rmdirSync(dest)
+    }
+  }
+}
+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/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.4",
+  "version": "4.1.1",
   "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.4",
-  "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.1",
+  "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.4",
-  "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.1",
+  "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.

package/skills/fde/references/business-case.md

@@ -1,5 +1,7 @@
 # business-case - Build the business case
 
+**Context:** apply [task context and evidence](task-context.md) before using the named records below.
+
 **Enter when:** the sponsor needs justification for the next phase, the FDE needs to defend budget or timeline, a feature decision needs cost/benefit evidence, or poc produced a direction that needs funding.
 
 **Read first:** `reality.md`, `success.md`, `delivery.md`, `context.md`. Load `business-case.md` from poc if it exists - extend it, don't restart.
@@ -12,7 +14,7 @@ Technical FDEs lose engagements by shipping good code without business justifica
 
 | Cost type | How to find it | Example |
 |-----------|---------------|---------|
-| **Direct cost** | Ask: "What does this problem cost per month in money?" | Manual reconciliation: 3 people × 8h/week × loaded cost = $X/month |
+| **Labor capacity / direct spend** | Ask: "What does this problem cost per month in money?" | Manual reconciliation hours × loaded rate = capacity value; separately identify reducible spend |
 | **Opportunity cost** | Ask: "What can't you do because of this problem?" | Can't onboard enterprise clients because the API can't handle their volume |
 | **Risk cost** | Ask: "What happens if this breaks at the worst time?" | A payment processing outage during Black Friday = $X/hour in lost sales |
 | **Velocity cost** | Measure: deployment frequency, lead time, change failure rate | Team ships once/month instead of once/week; each delay = N features not reaching customers |
@@ -22,17 +24,17 @@ Technical FDEs lose engagements by shipping good code without business justifica
 ```
 Investment: <hours × rate, or fixed cost>
   → Delivers: <specific outcome from success.md>
-    → Saves: <cost-of-nothing × probability of success>
-      → Net: savings - investment over <time horizon>
+    → Benefit: <capacity released, avoidable cash spend, revenue, or risk reduction>
+      → Net cash: realizable incremental cash benefit - full costs over <time horizon>
 ```
 
-Keep the drivers explicit. "We estimate $200K savings" means nothing. "3 people × 8h/week × $75/h × 52 weeks = $93.6K/year, minus $40K build cost = $53.6K net year one" is defensible.
+Keep drivers, units, sources, and ranges explicit. For example, 3 people × 8h/week × $75/h × 52 weeks = $93.6K/year of labor capacity value. It is cash savings only if spend actually falls (for example, paid overtime or a contractor cost ends). Name who can realize the benefit and how. Include build, ongoing operation, adoption, and transition costs; avoid double-counting capacity and revenue enabled by the same hours. Do not calculate cash payback from capacity value alone.
 
 **3. Sensitivity check - name the two drivers that swing the result:**
 
 Every business case has 1-2 variables where a small change flips the outcome. Name them explicitly:
 
-> "This case holds if the team actually reclaims 6+ hours/week per person. If it's only 3 hours, the payback extends from 5 months to 14 months. The validation: measure time-spent before and after pilot with 2 team members."
+> "The capacity case assumes the team reclaims 6 hours/week per person. At 3 hours, that benefit halves. Cash payback remains unproven until finance identifies avoidable spend. Validate time-spent before and after the pilot with representative team members."
 
 The sponsor who sees you've identified where the case could break trusts the case more, not less.
 
@@ -53,7 +55,7 @@ The sponsor who sees you've identified where the case could break trusts the cas
 **The problem costs:** <one line, quantified>
 **The investment:** <hours and cost>
 **The return:** <quantified, with time horizon>
-**Payback:** <months>
+**Payback:** <months from realizable cash benefits, or not established>
 **Sensitivity:** <the 1-2 drivers that swing it, with thresholds>
 **Risks:** <what must be true for this to hold>
 **Recommendation:** <proceed / proceed-with-conditions / defer>
@@ -67,7 +69,7 @@ The sponsor who sees you've identified where the case could break trusts the cas
 
 ## Checkpoint
 
-Walk the FDE through: the cost of doing nothing (anchor), the investment, the return, and the one sensitivity that matters most. If the FDE says "the sponsor won't buy the ROI number" - ask what number they would believe and work backwards from there.
+Walk the FDE through: the cost of doing nothing (anchor), the investment, the return, and the one sensitivity that matters most. If the FDE says "the sponsor won't buy the ROI number," inspect the disputed inputs and sources, test plausible ranges, and identify what measurement would resolve the disagreement. Never reverse-engineer assumptions to hit a desired number.
 
 ## Worked example
 

package/skills/fde/references/close.md

@@ -1,8 +1,10 @@
 # close - Transfer operations
 
+**Context:** apply [task context and evidence](task-context.md) before using the named records below.
+
 **Enter when:** the engagement is ending - the customer team must run this without the FDE.
 
-**Read first:** bounded `fde handoff` or `fde resume`, then targeted `fde recall` for missing evidence. Build the full picture through relevant excerpts, not a full-directory load. Consult `terrain.md` only for the code paths needed by the successor.
+**Read first:** for standalone work, use the supplied permitted operating notes, evidence and ownership; no engagement binding or CLI command is required. For a bound engagement, use bounded `fde handoff` or `fde resume`, then targeted `fde recall` for missing evidence. Never initialize records merely to draft a handoff. Build the picture through relevant excerpts, not a full-directory load. Consult `terrain.md` only for code paths needed by the successor.
 
 The engagement doesn't end at ship. It ends when the customer can maintain what was built without calling.
 
@@ -20,10 +22,10 @@ The engagement doesn't end at ship. It ends when the customer can maintain what
 **1b. Value + receipts close gate (refuse green close if any fail):**
 - Primary value bucket in `success.md` matches what the sponsor funded; at least one ledger row has **Measured** (not forever-`pending`) with evidence **and a named customer-side owner in Accepted by** for that bucket - or the retrospective explicitly records “not measured; sponsor accepted pending.” A measured-but-unaccepted number closes as `claimed`; say so in the retrospective rather than closing green on arithmetic nobody signed.
 - Audit receipt exists for the final shipped path (exceptions/operating map walked; cite file).
-- Eval receipt: **n/a if no AI**, else final golden/eval result + HITL owner recorded; kill switch / fallback named in `handoff.md`.
+- Eval receipt: **n/a if no AI**, else final scoped eval result + operating owner and required human-review or bounded-automation authority recorded; kill switch / fallback named in `handoff.md`.
 - One line in the retrospective: which bucket moved, by how much, vs baseline.
 
-**2. The pattern.** Anything that happened here and will happen again - a compliance approach, a migration pattern, a stakeholder dynamic - gets encoded for reuse. **If you do it twice, encode it.**
+**2. The pattern.** Anything that happened here and will happen again - a compliance approach, a migration pattern, a stakeholder dynamic - gets encoded for reuse. Use [encode-pattern](encode-pattern.md) to distinguish candidate patterns from supported ones and protect customer data.
 
 **3. The handoff.** Operational knowledge for the person woken at 2am, not technical documentation: the 3 things that will break and the fix for each · who holds the tribal knowledge · what each alert means · deploy and rollback in plain language. AI components additionally: model version, what normal output looks like (so drift is recognisable), fallback behaviour, who owns retraining, **how to disable the AI path without taking down the feature** - without this the team turns it off at the first misbehaviour and it stays off.
 
@@ -41,7 +43,7 @@ The engagement doesn't end at ship. It ends when the customer can maintain what
 
 **Check the handoff as a lookup tool.** Give the intended operator one realistic task, such as finding the owner and recovery steps for a failed run. Can they locate the answer and its source in the permitted handoff without your explanation? A reader finding the instructions is not proof they can execute them; verify operation separately in the agreed safe environment. Correct the passage they could not use, rather than adding a longer introduction.
 
-If the operator is unavailable, a fresh reviewer can attempt the same lookup using only the permitted draft and task. Report this as a simulated clarity check, not operator validation, customer approval, or a green close. Use one focused pass for a consequential handoff; do not add a committee or a second approval ritual.
+If the operator is unavailable, a fresh reviewer can attempt the same lookup using only the permitted draft and task. Report this as a simulated clarity check, not operator validation, customer approval, or a green close. Claim independent review only if a separate reviewer actually performed it; identify the reviewer and evidence available. If none is available, perform a labeled self-check and report independent review as unperformed. Use one focused pass for a consequential handoff; do not add a committee or a second approval ritual.
 
 Direct assessment to the FDE: did the engagement achieve `success.md` · 2-3 lessons that matter · is the pattern worth encoding · is the handoff complete or where are the gaps. Also: value bucket + audit receipt green; eval **n/a or green**. Pending Measured without sponsor acceptance = gap, not green close. Honest - a gap named now is cheaper than a callback in six weeks.