nono-skills 0.1.0

package/plugin/skills/migration/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: migration
+description: Use when data, schema, API, dependency, platform, infrastructure, or runtime state must move between versions or systems while preserving service and recoverability.
+---
+
+# Migration
+
+## Purpose
+
+Design or execute a staged, observable, reversible transition with explicit compatibility windows, validation, and cleanup.
+
+## Inputs
+
+- Source and target states, invariants, data volume, traffic, and downtime tolerance
+- Producers, consumers, schemas, deployment topology, ownership, and operational constraints
+- Backfill, rollback, compliance, and retention requirements
+
+## Outputs
+
+- Migration phases, compatibility strategy, validation, monitoring, rollback, and cleanup criteria
+- If execution is authorized: migrations, adapters, backfills, tests, and runbook changes
+- Reconciliation evidence and remaining risk
+
+## Rules
+
+- Inspect all readers and writers before changing shared state.
+- Prefer expand-migrate-contract for live systems: introduce compatibility, move traffic or data, verify, then remove old paths.
+- Make reruns idempotent and define partial-failure recovery.
+- Validate counts plus business invariants; do not treat command success as data correctness.
+- Separate source implementation from production execution authorization.
+- Preserve backups and rollback paths appropriate to impact.
+
+## Decision-log updates
+
+Record compatibility windows, cutover criteria, data ownership, transformation rules, rollback limits, accepted downtime, and irreversible checkpoints. Link evidence for completing each phase.
+Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+
+## Escalate to the human
+
+Escalate before destructive or irreversible steps, production backfills or cutovers, downtime, data loss or semantic ambiguity, privacy-sensitive movement, or rollback beyond the stated tolerance.

package/plugin/skills/migration/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Migration"
+  short_description: "Plan reversible migrations with validation and rollback"
+  default_prompt: "Use $migration to design a staged, observable, and recoverable transition."

package/plugin/skills/plan/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: plan
+description: Use when a software direction is defined enough to map multi-step, cross-cutting, risky, or long-running work into a concrete execution plan before implementation.
+---
+
+# Plan
+
+## Purpose
+
+Turn the request and repository evidence into a decision-ready spec and a concise, verifiable execution map. Plan to the level warranted by risk; do not add ceremony to trivial work.
+
+## Inputs
+
+- User goal, constraints, and expected behavior
+- Applicable `AGENTS.md`, current code, tests, docs, issues, and runtime evidence
+- Existing `docs/agent/spec.md`, `plan.md`, and `decision-log.md`
+
+## Outputs
+
+- A decision-ready spec and concise execution map with testable acceptance criteria
+- When the artifact files already exist or the user requests durable planning, updated `docs/agent/spec.md` and `docs/agent/plan.md`
+- A short summary of assumptions and human decisions needed
+
+## Rules
+
+- Inspect the real code path before decomposing implementation work.
+- Separate confirmed facts, inferences, and unresolved choices.
+- Keep work items outcome-based and independently verifiable; avoid file-by-file pseudo-instructions.
+- Include compatibility, migration, rollout, observability, and rollback work only when relevant.
+- Do not edit production code while the request is planning-only.
+- Re-plan when new evidence invalidates a premise rather than defending the old plan.
+
+## Decision-log updates
+
+Record scope interpretations, contract choices, rejected approaches with non-obvious tradeoffs, and material re-plans. Link each entry to the affected plan item.
+Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+
+## Escalate to the human
+
+Escalate when competing interpretations change user-visible behavior, a required system or owner is outside scope, risk cannot be bounded, or the plan requires destructive operations, production access, significant spend, or a product decision. Otherwise state reasonable assumptions and proceed.

package/plugin/skills/plan/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Plan"
+  short_description: "Turn complex work into a verifiable execution plan"
+  default_prompt: "Use $plan to turn this task into a concise, verifiable execution plan."

package/plugin/skills/refactor/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: refactor
+description: Use when internal code structure, naming, duplication, coupling, complexity, or module boundaries should improve without changing externally observable behavior.
+---
+
+# Refactor
+
+## Purpose
+
+Improve changeability and clarity while preserving behavior and keeping the diff proportionate to a concrete maintenance problem.
+
+## Inputs
+
+- Refactoring goal or documented code smell
+- Existing behavior, public contracts, tests, dependency graph, and performance constraints
+- Current repository conventions
+
+## Outputs
+
+- Focused structural changes with stable or improved tests
+- Before-and-after explanation tied to the maintenance goal
+- Verification that behavior and relevant performance remain acceptable
+
+## Rules
+
+- Establish a behavioral safety net before structural change; add characterization tests when needed.
+- Separate behavior changes from refactoring so reviewers can reason about each.
+- Optimize for deeper modules, clear ownership, and reduced knowledge leakage, not smaller files by default.
+- Do not create abstractions without repeated variation or a proven boundary.
+- Preserve public APIs, persistence formats, error semantics, and ordering unless explicitly authorized.
+- Measure rather than assume performance-sensitive equivalence.
+
+## Decision-log updates
+
+Record new module boundaries, ownership changes, intentionally retained debt, compatibility constraints, and abstraction choices with long-term consequences. Routine renames and local cleanup do not need entries.
+Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+
+## Escalate to the human
+
+Escalate when preserving behavior is impossible or unprovable, the refactor implies a public or data contract change, scope grows across ownership boundaries, or the safety net is too weak for the risk.

package/plugin/skills/refactor/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Refactor"
+  short_description: "Improve internal structure while preserving behavior"
+  default_prompt: "Use $refactor to improve this structure while preserving observable behavior."

package/plugin/skills/release-readiness/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: release-readiness
+description: Use when a change, branch, build, migration, or release candidate must be assessed before merge, deployment, rollout, or handoff.
+---
+
+# Release Readiness
+
+## Purpose
+
+Produce an evidence-backed `ready`, `not ready`, or `ready with accepted risks` verdict. Assessment does not authorize release actions.
+
+## Inputs
+
+- Release scope, target environment, acceptance criteria, and rollout expectations
+- Current worktree or candidate, CI results, tests, findings, migrations, docs, and operational signals
+- Rollback, observability, compatibility, and ownership information
+
+## Outputs
+
+- Verdict with blockers, accepted risks, and evidence
+- Checklist covering code quality, tests, build, security, data change, compatibility, observability, rollback, docs, and support readiness as applicable
+- Exact unverified items and required next actions
+
+## Rules
+
+- Inspect current state; do not rely on stale claims that checks passed.
+- Run the strongest safe local checks and distinguish local proof from CI, staging, and production proof.
+- Treat code complete, merge ready, deploy ready, deployed, and verified in production as separate states.
+- Block on open critical or high findings unless risk is explicitly accepted by the proper owner.
+- Do not merge, tag, publish, deploy, or migrate without explicit authorization.
+
+## Decision-log updates
+
+Record risk acceptance, waived gates, rollout or rollback choices, and readiness verdict changes with evidence. Link unresolved findings and owners.
+Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+
+## Escalate to the human
+
+Escalate for blocked gates, missing rollback for high-risk changes, unresolved ownership, destructive migration, compliance or security risk, production action, or any request to waive a required control.

package/plugin/skills/release-readiness/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Release Readiness"
+  short_description: "Judge readiness from current verification evidence"
+  default_prompt: "Use $release-readiness to decide whether this candidate is ready and identify every blocker."

package/plugin/skills/review/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: review
+description: Use for a general objective code, diff, PR, or fix review without edits; use security-review when security is the primary assessment objective.
+---
+
+# Review
+
+## Purpose
+
+Find actionable correctness, compatibility, security, reliability, and maintainability defects in the requested change or scope. Review is read-only.
+
+## Inputs
+
+- Review baseline and target: diff, commit, branch, files, or stated behavior
+- Requirements, acceptance criteria, applicable instructions, tests, and runtime evidence
+- Existing findings and decision records
+
+## Outputs
+
+- Findings ordered `critical`, `high`, `medium`, then `low`
+- Each finding includes location, evidence, impact, reasoning or reproduction, and remediation direction
+- Residual risks and verification gaps; explicitly state when no actionable findings remain
+
+## Rules
+
+- Establish the exact review boundary and inspect the current artifact, not an assumed stale state.
+- Trace affected runtime and data paths beyond the diff when needed to prove impact.
+- Prioritize defects over style preferences. Do not invent issues for report completeness.
+- Distinguish verified defects from questions and speculative risks.
+- Do not modify code or mark a finding fixed without evidence.
+
+## Decision-log updates
+
+Record only review-scope interpretations or accepted risk decisions that future work must preserve. Put individual defects in an existing `docs/agent/findings.md`; otherwise report them in the final response.
+Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+
+## Escalate to the human
+
+Escalate when the baseline is ambiguous and changes the verdict, required evidence is inaccessible, a suspected critical issue could expose users or data, or the review requires live destructive testing. Otherwise complete the strongest safe review and disclose the gap.

package/plugin/skills/review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Review"
+  short_description: "Find actionable defects in a code change or fix"
+  default_prompt: "Use $review to find evidence-backed defects in this change without editing it."

package/plugin/skills/security-review/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: security-review
+description: Use when security is the primary assessment objective for code, configuration, architecture, identities, data handling, or a change set.
+---
+
+# Security Review
+
+## Purpose
+
+Identify plausible, evidence-backed security weaknesses across trust boundaries, attacker-controlled inputs, identities, secrets, data, and operational controls. Review is read-only.
+
+## Inputs
+
+- Defined scope, threat assumptions, and deployment context
+- Code, dependencies, configuration, infrastructure, schemas, and auth flows
+- Existing security findings, tests, and compensating controls
+
+## Outputs
+
+- Findings ordered by exploitability and impact, with evidence and attack path
+- Affected assets, preconditions, remediation direction, and confidence
+- Coverage limits and residual risks
+
+## Rules
+
+- Map trust boundaries and attacker capabilities before applying checklists.
+- Check authentication, authorization, injection, XSS, CSRF, SSRF, secret handling, cryptography, data exposure, dependency risk, abuse controls, and logging where relevant.
+- Never include live secrets, exploit unrelated systems, or perform destructive testing.
+- Distinguish confirmed vulnerabilities from hardening opportunities.
+- Do not edit code unless the user separately requests remediation.
+
+## Decision-log updates
+
+Keep vulnerabilities in an existing `docs/agent/findings.md`; otherwise report sanitized findings in the final response. Log only accepted security tradeoffs, threat-model assumptions, compensating controls, or risk acceptance decisions.
+Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+
+## Escalate to the human
+
+Escalate immediately for plausible critical exposure, active compromise indicators, secrets in version control, testing that may affect real users, or remediation requiring risk acceptance. Avoid broadcasting sensitive details beyond the authorized audience.

package/plugin/skills/security-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Security Review"
+  short_description: "Assess trust boundaries and evidence-backed security risk"
+  default_prompt: "Use $security-review to assess this scope for plausible, evidence-backed security weaknesses."

package/plugin/skills/test/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: test
+description: Use when software behavior needs new or improved unit, integration, contract, end-to-end, edge-case, or regression tests, or when test coverage must be assessed.
+---
+
+# Test
+
+## Purpose
+
+Create the smallest reliable test set that proves important behavior and failure modes through stable public seams.
+
+## Inputs
+
+- Behavioral contract, bug report, acceptance criteria, or changed code
+- Existing test architecture, fixtures, commands, and coverage gaps
+- Relevant runtime, data, and external-system boundaries
+
+## Outputs
+
+- Focused automated tests and minimal necessary test utilities
+- Exact commands and results
+- Documented gaps that cannot be tested safely or deterministically
+
+## Rules
+
+- Prefer behavior assertions over implementation-detail assertions.
+- For a bug, first demonstrate the failure when practical, then verify the fix.
+- Cover happy path, meaningful boundaries, errors, permissions, and regression risk in proportion to impact.
+- Use real components where practical; mock only unstable or external boundaries.
+- Eliminate flaky timing, shared-state leakage, order dependence, and production dependencies.
+- Do not change production semantics merely to make a weak test pass.
+
+## Decision-log updates
+
+Record material test-boundary choices, intentionally excluded coverage, chosen substitutes for unavailable dependencies, and risk accepted because a scenario cannot be automated. Routine test cases do not need entries.
+Use an existing `docs/agent/decision-log.md`. If it is absent, include the decision in the final response; create workflow artifacts only when the user requests them.
+
+## Escalate to the human
+
+Escalate when validation requires production data or destructive actions, expected behavior is undefined, the available environment cannot provide meaningful proof, or the requested test conflicts with privacy, cost, or reliability constraints.

package/plugin/skills/test/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Test"
+  short_description: "Design focused tests for behavior and regression risk"
+  default_prompt: "Use $test to prove the important behavior and regression risks in this scope."

package/scripts/validate.mjs

@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { listFiles } from '../src/fs-safe.js';
+
+const root = path.resolve(import.meta.dirname, '..');
+const packageJson = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+const plugin = JSON.parse(await readFile(path.join(root, 'plugin', '.codex-plugin', 'plugin.json'), 'utf8'));
+assert.equal(plugin.name, 'engineering');
+assert.equal(plugin.version, packageJson.version);
+
+const skillRoot = path.join(root, 'plugin', 'skills');
+const skillFiles = (await listFiles(skillRoot)).filter((file) => file.endsWith('/SKILL.md'));
+assert.equal(skillFiles.length, 15);
+for (const relative of skillFiles) {
+  const expectedName = relative.split(path.sep)[0];
+  const content = await readFile(path.join(skillRoot, relative), 'utf8');
+  const metadata = await readFile(path.join(skillRoot, expectedName, 'agents', 'openai.yaml'), 'utf8');
+  const shortDescription = metadata.match(/short_description: "([^"]+)"/)?.[1];
+  assert.match(content, new RegExp(`^---\\nname: ${expectedName}\\ndescription: .+\\n---`, 's'));
+  assert.doesNotMatch(content, /TODO|Superpowers|\.codex\/skills/);
+  assert.match(content, /create workflow artifacts only when the user requests them/);
+  assert.ok(shortDescription && shortDescription.length >= 25 && shortDescription.length <= 64);
+  assert.doesNotMatch(metadata, /Reusable engineering workflow|for this task\./);
+  assert.match(metadata, new RegExp(`default_prompt: ".*\\$${expectedName.replaceAll('-', '\\-')}\\b`));
+}
+
+console.log(`Validated engineering plugin ${plugin.version} with ${skillFiles.length} skills.`);

package/src/cli.js

@@ -0,0 +1,85 @@
+const COMMANDS = new Set(['install', 'init', 'update', 'doctor', 'uninstall']);
+
+export const HELP = `nono-skills <command> [options]
+
+Commands:
+  install                 Install the engineering Codex plugin
+  init [directory]        Add project guidance and agent artifacts
+  update                  Update an owned plugin installation
+  doctor                  Diagnose the plugin installation
+  uninstall               Remove the owned plugin installation
+
+Options:
+  --dry-run               Show project changes without writing
+  --force                 Back up and replace conflicting project files
+  --purge-project <path>  Remove unchanged installed project artifacts
+  --version               Print package version
+  --help                  Show this help
+`;
+
+export function parseArgs(argv) {
+  const result = {
+    command: 'help', target: undefined, force: false, dryRun: false,
+    purgeProject: undefined, help: false, version: false,
+  };
+  const args = [...argv];
+  if (args.length === 0) {
+    result.help = true;
+    return result;
+  }
+  if (args[0] === '--version') {
+    result.command = 'version';
+    result.version = true;
+    return result;
+  }
+  if (args[0] === '--help' || args[0] === '-h') {
+    result.help = true;
+    return result;
+  }
+  result.command = args.shift();
+  while (args.length) {
+    const arg = args.shift();
+    if (arg === '--force') result.force = true;
+    else if (arg === '--dry-run') result.dryRun = true;
+    else if (arg === '--help' || arg === '-h') result.help = true;
+    else if (arg === '--purge-project') result.purgeProject = args.shift();
+    else if (!arg.startsWith('-') && result.command === 'init' && result.target === undefined) result.target = arg;
+    else throw new Error(`Unknown option: ${arg}`);
+  }
+  return result;
+}
+
+export async function run(argv, context) {
+  const stdout = context.stdout ?? process.stdout;
+  const stderr = context.stderr ?? process.stderr;
+  let options;
+  try {
+    options = parseArgs(argv);
+  } catch (error) {
+    stderr.write(`${error.message}\n`);
+    return 1;
+  }
+  if (options.version) {
+    stdout.write(`${context.version ?? '0.1.0'}\n`);
+    return 0;
+  }
+  if (options.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+  if (!COMMANDS.has(options.command)) {
+    stderr.write(`Unknown command: ${options.command}\n`);
+    return 1;
+  }
+  const handler = context.handlers?.[options.command];
+  if (!handler) {
+    stderr.write(`Command is not available: ${options.command}\n`);
+    return 1;
+  }
+  try {
+    return await handler(options, context);
+  } catch (error) {
+    stderr.write(`${error.message}\n`);
+    return 1;
+  }
+}

package/src/codex.js

@@ -0,0 +1,13 @@
+import { spawn } from 'node:child_process';
+
+export function runCodex(args, { env = process.env, cwd = process.cwd() } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn('codex', args, { env, cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', (error) => resolve({ code: 127, stdout, stderr: error.message }));
+    child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }));
+  });
+}

package/src/commands.js

@@ -0,0 +1,98 @@
+import { readFile, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+import { runCodex as defaultRunCodex } from './codex.js';
+import { diagnose } from './doctor.js';
+import { listFiles, sha256File } from './fs-safe.js';
+import { installPlugin, updatePlugin } from './plugin-install.js';
+import { writeJsonAtomic } from './plugin-state.js';
+import { applyProjectInit, planProjectInit } from './project-init.js';
+import { purgeProject, uninstallPlugin } from './uninstall.js';
+
+async function exists(file) {
+  try { await stat(file); return true; }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+function timestamp() {
+  return new Date().toISOString().replaceAll(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+}
+
+export function createHandlers(base) {
+  const stdout = base.stdout ?? process.stdout;
+  const stderr = base.stderr ?? process.stderr;
+  const runCodex = base.runCodex ?? defaultRunCodex;
+  const removePlugin = base.uninstallPlugin ?? uninstallPlugin;
+  const pluginContext = () => ({
+    home: base.home,
+    packageRoot: base.packageRoot,
+    packageVersion: base.packageVersion,
+    runCodex,
+    clock: base.clock ?? timestamp,
+  });
+
+  return {
+    async install() {
+      const result = await installPlugin(pluginContext());
+      stdout.write(`Engineering plugin ${result.status} (${result.pluginVersion}). Start a new Codex task to activate it.\n`);
+      return 0;
+    },
+
+    async update() {
+      const result = await updatePlugin(pluginContext());
+      stdout.write(`Engineering plugin ${result.status} (${result.pluginVersion}). Start a new Codex task to activate it.\n`);
+      return 0;
+    },
+
+    async init(options) {
+      const targetRoot = path.resolve(base.cwd, options.target ?? '.');
+      const templateRoot = path.join(base.packageRoot, 'templates');
+      const actions = await planProjectInit({
+        templateRoot, targetRoot, force: options.force, dryRun: options.dryRun, clock: base.clock ?? timestamp,
+      });
+      const conflicts = actions.filter((action) => action.type === 'conflict');
+      if (conflicts.length) {
+        stderr.write(`Conflicts detected; no files written:\n${conflicts.map((action) => `- ${action.relative}`).join('\n')}\nUse --force to back up and replace them.\n`);
+        return 1;
+      }
+      const results = await applyProjectInit(actions);
+      if (!options.dryRun) {
+        const files = await listFiles(templateRoot);
+        const checksums = {};
+        for (const relative of files) checksums[relative] = await sha256File(path.join(targetRoot, relative));
+        await writeJsonAtomic(path.join(targetRoot, '.codex-engineering-skills.json'), {
+          schemaVersion: 1, packageVersion: base.packageVersion, files: checksums,
+        });
+      }
+      const count = (type) => results.filter((result) => result.type === type).length;
+      stdout.write(`${options.dryRun ? 'Would create' : 'Created'} ${count('create')}, replaced ${count('replace')}, skipped ${count('skip')}.\n`);
+      return 0;
+    },
+
+    async doctor() {
+      const checks = await diagnose({ home: base.home, packageVersion: base.packageVersion, runCodex });
+      for (const check of checks) stdout.write(`${check.status.toUpperCase()} ${check.name}: ${check.detail}\n`);
+      return checks.some((check) => check.status === 'fail') ? 1 : 0;
+    },
+
+    async uninstall(options) {
+      let purgeState;
+      let purgeTarget;
+      if (options.purgeProject) {
+        purgeTarget = path.resolve(base.cwd, options.purgeProject);
+        const statePath = path.join(purgeTarget, '.codex-engineering-skills.json');
+        if (!await exists(statePath)) throw new Error(`Project ownership state not found: ${statePath}`);
+        purgeState = JSON.parse(await readFile(statePath, 'utf8'));
+      }
+      await removePlugin({ home: base.home, runCodex });
+      stdout.write('Engineering plugin uninstalled. Project artifacts were preserved.\n');
+      if (purgeState) {
+        const statePath = path.join(purgeTarget, '.codex-engineering-skills.json');
+        const result = await purgeProject({ targetRoot: purgeTarget, recordedChecksums: purgeState.files });
+        if (result.preserved.length === 0) await rm(statePath);
+        stdout.write(`Purged ${result.removed.length}; preserved ${result.preserved.length} modified files.\n`);
+      }
+      return 0;
+    },
+  };
+}

package/src/doctor.js

@@ -0,0 +1,40 @@
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+import { listFiles } from './fs-safe.js';
+import { verifyOwnership } from './plugin-state.js';
+
+async function exists(file) {
+  try { await stat(file); return true; }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+export async function diagnose({ home, packageVersion, runCodex }) {
+  const checks = [];
+  const codex = await runCodex(['--version']);
+  checks.push({ name: 'codex', status: codex.code === 0 ? 'pass' : 'fail', detail: codex.stdout || codex.stderr || 'unavailable' });
+
+  const pluginRoot = path.join(home, 'plugins', 'engineering');
+  const statePath = path.join(pluginRoot, '.installer-state.json');
+  const sourceExists = await exists(pluginRoot);
+  checks.push({ name: 'source', status: sourceExists ? 'pass' : 'fail', detail: sourceExists ? pluginRoot : 'plugin source missing' });
+
+  if (!sourceExists || !await exists(statePath)) {
+    checks.push({ name: 'ownership', status: 'fail', detail: 'installer ownership manifest missing' });
+    checks.push({ name: 'version', status: 'fail', detail: 'version unavailable' });
+    checks.push({ name: 'skills', status: 'fail', detail: 'skills unavailable' });
+  } else {
+    const state = JSON.parse(await readFile(statePath, 'utf8'));
+    const ownership = await verifyOwnership(state, pluginRoot);
+    checks.push({ name: 'ownership', status: ownership.valid ? 'pass' : 'fail', detail: ownership.valid ? 'checksums match' : `changed: ${ownership.mismatches.join(', ')}` });
+    checks.push({ name: 'version', status: state.packageVersion === packageVersion ? 'pass' : 'warn', detail: `installed ${state.packageVersion}; package ${packageVersion}` });
+    const files = await listFiles(path.join(pluginRoot, 'skills'));
+    const count = files.filter((file) => file.endsWith('/SKILL.md') || file === 'SKILL.md').length;
+    checks.push({ name: 'skills', status: count === 15 ? 'pass' : 'fail', detail: `${count} skills found` });
+  }
+
+  const registration = codex.code === 0 ? await runCodex(['plugin', 'list']) : codex;
+  const registered = registration.code === 0 && registration.stdout.includes('engineering@');
+  checks.push({ name: 'registration', status: registered ? 'pass' : 'fail', detail: registered ? 'installed and visible' : registration.stderr || 'not registered' });
+  return checks;
+}

package/src/fs-safe.js

@@ -0,0 +1,38 @@
+import { createHash } from 'node:crypto';
+import { readdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const IGNORED_FILE_NAMES = new Set(['.DS_Store']);
+
+export async function listFiles(root, relative = '') {
+  const directory = path.join(root, relative);
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (IGNORED_FILE_NAMES.has(entry.name)) continue;
+    const child = path.join(relative, entry.name);
+    if (entry.isDirectory()) files.push(...await listFiles(root, child));
+    else if (entry.isFile()) files.push(child);
+  }
+  return files;
+}
+
+export async function sha256File(file) {
+  const content = await readFile(file);
+  return createHash('sha256').update(content).digest('hex');
+}
+
+export async function filesEqual(left, right) {
+  try {
+    return await sha256File(left) === await sha256File(right);
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+export async function writeFileAtomic(file, content) {
+  const temporary = `${file}.tmp-${process.pid}-${Date.now()}`;
+  await writeFile(temporary, content, { mode: 0o600 });
+  await rename(temporary, file);
+}