@deniscodp/skills 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeniscoDp5
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# Programming Flow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Workflow riutilizzabile per bug e feature: esplorazione del progetto, specifica, implementazione
+a sessioni e misurazione dei risultati con Codex CLI e Claude Code CLI.
+
+## Installare le skill in un progetto
+
+Dalla cartella del progetto, con Node 20 o superiore:
+
+```sh
+npx @deniscodp/skills install
+```
+
+In un terminale il comando chiede i provider (claude preselezionato) e le skill opzionali, mostra il
+piano (cartelle, file da creare, aggiornare o rimuovere, conflitti) e scrive solo dopo la conferma.
+Rilanciato, aggiorna le skill già installate. Senza terminale e senza `--yes` stampa il piano e non scrive.
+
+| Flag | Effetto |
+|---|---|
+| `--provider <lista>` | `claude`, `codex`, `agy`, `gemini`, separati da virgole (predefinito `claude`) |
+| `--with <lista>` | skill opzionali: `denisco-workflow-benchmark`, `grill-me`, `grilling` |
+| `--target <cartella>` | progetto di destinazione (predefinito la cartella corrente) |
+| `--yes` | nessuna domanda e nessuna conferma: usa flag e valori predefiniti |
+| `--dry-run` | stampa il piano senza scrivere |
+| `--help`, `--version` | uso del comando e versione del pacchetto |
+
+Esempi senza domande:
+
+```sh
+npx @deniscodp/skills install --provider claude,codex --yes
+npx @deniscodp/skills install --provider codex,agy,gemini --with grill-me --dry-run
+npx @deniscodp/skills install --with denisco-workflow-benchmark --yes
+```
+
+| Provider | Cartella nel progetto |
+|---|---|
+| `claude` (Claude Code) | `.claude/skills` |
+| `codex` (Codex CLI), `agy` (Antigravity), `gemini` (Gemini CLI) | `.agents/skills`, una sola installazione condivisa |
+
+Le 5 skill `denisco-*` del workflow sono sempre installate; `denisco-workflow-benchmark` è spenta
+di default. Ogni cartella ha un manifest `.workflow-install.json`: un file modificato a mano, un file
+gestito che non serve più o la cartella di una consigliata già presente ma non installata dal comando
+fermano tutto prima di scrivere, e il codice d'uscita è diverso da 0.
+
+**Skill consigliate esterne.** `grill-me` porta con sé `grilling`, da cui dipende. Entrambe sono di
+Matt Pocock, con licenza MIT, e vengono scaricate al momento dell'installazione dall'ultima versione
+del ramo `main` di [mattpocock/skills](https://github.com/mattpocock/skills): non sono fissate a una
+versione e il loro contenuto può cambiare fra un'installazione e l'altra. Il piano mostra il commit
+scaricato. Se il download fallisce non viene scritto nulla: riprova più tardi o installa senza la skill
+consigliata. Con la variabile `GITHUB_TOKEN` le chiamate all'API di GitHub usano il token, mai stampato.
+
+Dettagli su aggiornamenti, migrazione dei nomi e installazione da un clone sono nella
+[guida operativa](docs/guides/workflow.md#installare-le-skill-in-un-progetto).
+
+## Da dove iniziare
+
+- [Guida operativa](docs/guides/workflow.md)
+- [Preparare ed eseguire i benchmark](docs/guides/benchmarks.md)
+- [Aggiungere skill e documentazione](docs/contributing.md)
+
+## Struttura
+
+```text
+skills/               Skill distribuibili, ciascuna con risorse e script propri
+docs/guides/          Guide trasversali per usare il workflow
+docs/contributing.md  Convenzioni per estendere il toolkit
+bin/                  Binario deniscodp-skills del pacchetto npm
+scripts/              Comando di installazione, catalogo delle consigliate e strumenti di manutenzione
+tests/                Test automatici del toolkit
+```
+
+Se prepari prove o misurazioni, i registri locali vanno in `.workflow-bench/` e le prove isolate in
+`.benchmark-work/`, entrambi esclusi da Git: un clone nuovo non li contiene.
+
+## Skill disponibili
+
+- [denisco-project-context](skills/denisco-project-context/SKILL.md): esplorazione e procedure del progetto.
+- [denisco-interactive-spec-definition](skills/denisco-interactive-spec-definition/SKILL.md): specifica e handoff.
+- [denisco-handoff-implementation](skills/denisco-handoff-implementation/SKILL.md): piano ed esecuzione fino a uno stop reale.
+- [denisco-implementation-coordinator](skills/denisco-implementation-coordinator/SKILL.md): percorso predefinito con almeno due blocchi; porta l'handoff a un piano di coordinamento lanciabile, poi gestisce programmatori sequenziali leggeri con contesti nuovi, incarichi delimitati e un report per incarico.
+- [denisco-visual-check](skills/denisco-visual-check/SKILL.md): verifica dei requisiti percettivi.
+- [denisco-workflow-benchmark](skills/denisco-workflow-benchmark/SKILL.md): misurazione e confronto dei risultati.
+
+Con Node 20+: `npm ci --ignore-scripts`, `npm test`, `npm run validate`.
+Il comando stabile del benchmark, dalla radice del repository, è `npm run bench -- help`.
+Installazione e validazione scoprono automaticamente le skill in `skills/`; le consigliate esterne
+sono elencate in `scripts/recommended.mjs`.
+
+I test locali non lanciano modelli. Nessun miglioramento di token o qualità è dichiarato prima
+delle prove con agenti: questa versione fornisce gli strumenti per misurarlo.

package/bin/deniscodp-skills.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../scripts/cli.mjs';
+
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@deniscodp/skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Install the denisco agent workflow skills into the current project for Claude Code, Codex, Antigravity and Gemini CLI.",
+  "license": "MIT",
+  "type": "module",
+  "engines": { "node": ">=20" },
+  "bin": { "deniscodp-skills": "bin/deniscodp-skills.mjs" },
+  "files": [
+    "bin/deniscodp-skills.mjs",
+    "scripts/catalog.mjs",
+    "scripts/cli.mjs",
+    "scripts/install.mjs",
+    "scripts/recommended.mjs",
+    "skills/denisco-*/**"
+  ],
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "test": "node --test tests/usage.test.mjs tests/workflow.test.mjs tests/catalog.test.mjs tests/handoff.test.mjs tests/ownership.test.mjs tests/cli.test.mjs",
+    "test:network": "node --test tests/network.test.mjs",
+    "validate": "node scripts/validate.mjs",
+    "bench": "node skills/denisco-workflow-benchmark/scripts/bench.mjs"
+  },
+  "dependencies": { "yaml": "^2.8.1" }
+}

package/scripts/catalog.mjs

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseDocument } from 'yaml';
+import { listFiles, rejectSymlinkPath } from '../skills/denisco-workflow-benchmark/scripts/io.mjs';
+
+export const repository = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export function resolveSkillsRoot(source = repository) {
+  const nested = path.resolve(source, 'skills');
+  // Accept the repository root or an already flat source/installed skill bundle.
+  return fs.existsSync(nested) && fs.statSync(nested).isDirectory() && !fs.existsSync(path.join(nested, 'SKILL.md'))
+    ? nested : path.resolve(source);
+}
+
+export function validateMarkdown(file, skillRoot) {
+  const text = fs.readFileSync(file, 'utf8');
+  for (const match of text.matchAll(/\[[^\]]+\]\(([^)]+)\)/g)) {
+    const destination = match[1].replace(/^<|>$/g, '').split('#')[0];
+    if (!destination || /^[a-z]+:/i.test(destination) || destination.startsWith('/') || destination.includes('<')) continue;
+    const target = path.resolve(path.dirname(file), destination);
+    if (skillRoot) {
+      const relative = path.relative(skillRoot, target);
+      if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(`${file}: skill resource must stay inside its package: ${destination}`);
+      }
+    }
+    if (!fs.existsSync(target)) throw new Error(`${file}: broken link ${destination}`);
+  }
+  if (/\b(?:TODO|TBD|FIXME)\b/.test(text)) throw new Error(`Unfinished marker: ${file}`);
+}
+
+// Frontmatter rules shared by packaged and downloaded skills: parseable YAML, a name equal to the
+// skill directory and a non-empty description.
+export function skillFrontmatter(text, name, file) {
+  const content = text.replace(/^/, '');
+  const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!frontmatter) throw new Error(`Missing frontmatter: ${file}`);
+  const parsed = parseDocument(frontmatter[1], { uniqueKeys: true });
+  if (parsed.errors.length) throw new Error(`Invalid YAML: ${file}: ${parsed.errors.join('; ')}`);
+  const metadata = parsed.toJSON();
+  if (!metadata || metadata.name !== name) throw new Error(`Skill name must match directory: ${file}`);
+  if (typeof metadata.description !== 'string' || !metadata.description.trim()) throw new Error(`Missing skill description: ${file}`);
+  return metadata;
+}
+
+export function discoverSkills(source = repository) {
+  const root = resolveSkillsRoot(source);
+  rejectSymlinkPath(root);
+  const skills = [];
+  const entries = fs.readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) throw new Error(`Symlink skill source refused: ${entry.name}`);
+    if (!entry.isDirectory()) continue;
+    const directory = path.join(root, entry.name), file = path.join(directory, 'SKILL.md');
+    if (!fs.existsSync(file)) continue;
+    rejectSymlinkPath(file);
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(entry.name) || entry.name.length > 64) throw new Error(`Invalid skill directory name: ${entry.name}`);
+    const metadata = skillFrontmatter(fs.readFileSync(file, 'utf8'), entry.name, file);
+    if (!/^\d+\.\d+\.\d+$/.test(metadata.metadata?.version ?? '')) throw new Error(`Missing/invalid skill metadata.version: ${file}`);
+    const files = listFiles(directory);
+    const documents = files.filter(relative => relative.endsWith('.md')).map(relative => path.join(directory, relative));
+    for (const document of documents) validateMarkdown(document, directory);
+    skills.push({ name: entry.name, directory, metadata, files, documents });
+  }
+  if (!skills.length) throw new Error(`No valid skill directories found in ${root}`);
+  return skills;
+}

package/scripts/cli.mjs

@@ -0,0 +1,264 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { parseArgs } from 'node:util';
+import { repository } from './catalog.mjs';
+import { applyPlan, checkPlan, manifestSkills, planInstall, providerRoots } from './install.mjs';
+import { DownloadError, downloadRecommended, isRecommended, recommendedSkills, requiredBy, withDependencies } from './recommended.mjs';
+
+// Installed in every chosen root. Every other skill in the package is optional and listed below.
+export const coreSkills = Object.freeze([
+  'denisco-handoff-implementation',
+  'denisco-implementation-coordinator',
+  'denisco-interactive-spec-definition',
+  'denisco-project-context',
+  'denisco-visual-check'
+]);
+// Packaged optional skills first, then the recommended third-party skills downloaded from GitHub.
+export const optionalSkills = Object.freeze([
+  { name: 'denisco-workflow-benchmark', description: 'workflow measurement and benchmark tooling' },
+  ...recommendedSkills.map(skill => ({
+    name: skill.name,
+    description: `${skill.description}${skill.requires.length ? `, also installs ${skill.requires.join(', ')}` : ''} (github.com/${skill.repo}@${skill.ref}, ${skill.license})`
+  }))
+]);
+export const providers = Object.freeze(Object.keys(providerRoots));
+const defaultProviders = ['claude'];
+
+const usage = `Usage: npx @deniscodp/skills install [options]
+       deniscodp-skills install [options]
+
+Installs the denisco workflow skills into a project (default: the current directory).
+Without --yes it asks for providers and optional skills when run in a terminal, shows the plan
+and writes only after confirmation.
+
+Commands:
+  install              plan and install or update the skills
+
+Options:
+  --provider <list>    comma-separated: ${providers.join(', ')} (default: ${defaultProviders.join(',')})
+                       claude -> .claude/skills; codex, agy, gemini -> .agents/skills
+  --with <list>        comma-separated optional skills: ${optionalSkills.map(s => s.name).join(', ')}
+                       ${recommendedSkills.map(s => s.name).join(', ')}: downloaded from GitHub (latest main)
+  --target <dir>       project folder (default: current directory)
+  --yes                no questions and no confirmation: use flags and defaults
+  --dry-run            print the plan without writing
+  -h, --help           show this help
+  -v, --version        show the package version
+`;
+
+class UsageError extends Error {}
+
+function list(value, allowed, label) {
+  const items = value.split(',').map(item => item.trim()).filter(Boolean);
+  if (!items.length) throw new UsageError(`Empty ${label} list`);
+  const unknown = items.filter(item => !allowed.includes(item));
+  if (unknown.length) throw new UsageError(`Unknown ${label}: ${unknown.join(', ')} (allowed: ${allowed.join(', ')})`);
+  return [...new Set(items)];
+}
+
+export function parseCommand(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv, allowPositionals: true, strict: true,
+      options: {
+        provider: { type: 'string' }, with: { type: 'string' }, target: { type: 'string' },
+        yes: { type: 'boolean' }, 'dry-run': { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' }
+      }
+    });
+  } catch (error) { throw new UsageError(error.message); }
+  const { values, positionals } = parsed;
+  if (positionals.length > 1 || (positionals[0] && positionals[0] !== 'install')) {
+    throw new UsageError(`Unknown command: ${positionals.join(' ')}`);
+  }
+  return {
+    command: positionals[0] ?? null,
+    help: Boolean(values.help), version: Boolean(values.version),
+    providers: values.provider === undefined ? null : list(values.provider, providers, 'provider'),
+    with: values.with === undefined ? [] : list(values.with, optionalSkills.map(s => s.name), 'optional skill'),
+    target: values.target ?? null, yes: Boolean(values.yes), dryRun: Boolean(values['dry-run'])
+  };
+}
+
+// Providers sharing a skills root produce one installation and one manifest.
+export function groupRoots(chosen) {
+  const groups = new Map();
+  for (const provider of chosen) {
+    const root = providerRoots[provider];
+    if (!groups.has(root)) groups.set(root, []);
+    groups.get(root).push(provider);
+  }
+  return [...groups].map(([root, members]) => ({ root, providers: members }));
+}
+
+// Optional skills already installed in a root stay selected by default: dropping them silently
+// would turn their files into stale managed files and stop the installation.
+function installedOptional(target, roots) {
+  const names = new Set(optionalSkills.map(s => s.name)), found = new Set();
+  for (const { root } of roots) {
+    for (const name of manifestSkills(path.join(path.resolve(target), root))) if (names.has(name)) found.add(name);
+  }
+  return found;
+}
+
+export function buildPlans({ target, roots, selected, source = repository, downloaded = [] }) {
+  const exclude = optionalSkills.map(s => s.name).filter(name => !isRecommended(name) && !selected.includes(name));
+  const external = downloaded.filter(skill => selected.includes(skill.name));
+  return roots.map(group => ({ ...group, plan: planInstall({ target, provider: group.providers[0], source, exclude, external }) }));
+}
+
+function blocking(plans) {
+  const problems = [];
+  for (const { plan } of plans) {
+    for (const item of [...plan.entries, ...plan.removals]) {
+      if (item.action === 'conflict') problems.push(`conflict: ${path.join(plan.root, item.key)} was modified locally after the last install`);
+    }
+    for (const name of plan.unmanaged) problems.push(`conflict: ${path.join(plan.root, name)} already exists and is not managed by this installer`);
+    for (const key of plan.stale) problems.push(`stale: ${path.join(plan.root, key)} is a managed file of a skill that is no longer selected or shipped`);
+  }
+  return problems;
+}
+
+export function describePlans(target, plans, downloaded = []) {
+  const lines = [`Target: ${path.resolve(target)}`];
+  for (const { name, source } of downloaded) {
+    lines.push(`Recommended ${name}: github.com/${source.repo}@${source.ref} (commit ${source.commit}), ${source.license} license, ${source.author}`);
+  }
+  for (const { root, providers: members, plan } of plans) {
+    const items = [...plan.entries, ...plan.removals];
+    const count = action => items.filter(item => item.action === action).length;
+    const skills = [...new Set(plan.entries.map(entry => entry.key.split('/')[0]))];
+    lines.push('', `${root} (${members.join(', ')})`, `  skills: ${skills.join(', ')}`);
+    lines.push(`  create ${count('create')}, update ${count('update')}, remove ${count('remove')}, unchanged ${count('unchanged')}, conflict ${count('conflict') + plan.unmanaged.length}, stale ${plan.stale.length}`);
+    for (const name of plan.unmanaged) lines.push(`  ${'conflict'.padEnd(8)} ${name}/ (folder not managed by this installer)`);
+    for (const item of items) {
+      if (['create', 'update', 'remove', 'conflict'].includes(item.action)) lines.push(`  ${item.action.padEnd(8)} ${item.key}`);
+    }
+    for (const key of plan.stale) lines.push(`  ${'stale'.padEnd(8)} ${key}`);
+  }
+  return lines.join('\n');
+}
+
+// Reads answers line by line; works with a terminal and with scripted input alike.
+function lineReader(input, output) {
+  const rl = readline.createInterface({ input, output, terminal: Boolean(input.isTTY && output.isTTY) });
+  const queue = [], waiting = [];
+  let closed = false;
+  rl.on('line', line => waiting.length ? waiting.shift()(line) : queue.push(line));
+  rl.on('close', () => { closed = true; while (waiting.length) waiting.shift()(null); });
+  return {
+    ask(question) {
+      output.write(question);
+      if (queue.length) return Promise.resolve(queue.shift());
+      if (closed) return Promise.resolve(null);
+      return new Promise(resolve => waiting.push(resolve));
+    },
+    close: () => rl.close()
+  };
+}
+
+async function askProviders(reader, out, preset) {
+  for (;;) {
+    const answer = await reader.ask(`Providers (${providers.join(', ')}), comma-separated [${preset.join(',')}]: `);
+    if (answer === null) return null;
+    if (!answer.trim()) return preset;
+    try { return list(answer, providers, 'provider'); } catch (error) { out.write(`${error.message}\n`); }
+  }
+}
+
+async function askOptional(reader, out, preset) {
+  if (!optionalSkills.length) return [];
+  const chosen = new Set(preset);
+  for (;;) {
+    out.write('\nOptional skills:\n');
+    // A dependency of a chosen skill is shown as selected, with the skill that requires it.
+    const effective = withDependencies([...chosen]);
+    optionalSkills.forEach((skill, i) => {
+      const needers = chosen.has(skill.name) ? [] : requiredBy(skill.name, effective);
+      const mark = chosen.has(skill.name) || needers.length ? 'x' : ' ';
+      out.write(`  ${i + 1}. [${mark}] ${skill.name} - ${skill.description}${needers.length ? ` (required by ${needers.join(', ')})` : ''}\n`);
+    });
+    const answer = await reader.ask('Numbers to toggle (e.g. 1,2), Enter to continue: ');
+    if (answer === null) return null;
+    if (!answer.trim()) return optionalSkills.map(s => s.name).filter(name => effective.includes(name));
+    for (const token of answer.split(',').map(t => t.trim()).filter(Boolean)) {
+      const skill = optionalSkills[Number(token) - 1];
+      if (!/^\d+$/.test(token) || !skill) { out.write(`Not an option: ${token}\n`); continue; }
+      if (chosen.has(skill.name)) chosen.delete(skill.name); else chosen.add(skill.name);
+    }
+  }
+}
+
+function packageVersion() {
+  return JSON.parse(fs.readFileSync(path.join(repository, 'package.json'), 'utf8')).version;
+}
+
+export async function main(argv, io = {}) {
+  const stdin = io.stdin ?? process.stdin, stdout = io.stdout ?? process.stdout, stderr = io.stderr ?? process.stderr;
+  const interactiveTerminal = io.interactive ?? Boolean(stdin.isTTY && stdout.isTTY);
+  let reader;
+  try {
+    const options = parseCommand(argv);
+    if (options.help) { stdout.write(usage); return 0; }
+    if (options.version) { stdout.write(`${packageVersion()}\n`); return 0; }
+    if (!options.command) { stderr.write(usage); return 1; }
+    const target = path.resolve(io.cwd ?? process.cwd(), options.target ?? '.');
+    if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) throw new UsageError(`Target folder does not exist: ${target}`);
+    const interactive = interactiveTerminal && !options.yes && !options.dryRun;
+    let chosenProviders = options.providers ?? defaultProviders;
+    if (interactive) {
+      reader = lineReader(stdin, stdout);
+      chosenProviders = await askProviders(reader, stdout, chosenProviders);
+      if (!chosenProviders) { stderr.write('Input closed: nothing written.\n'); return 1; }
+    }
+    const roots = groupRoots(chosenProviders);
+    let selected = [...new Set([...installedOptional(target, roots), ...options.with])];
+    if (interactive) {
+      selected = await askOptional(reader, stdout, selected);
+      if (!selected) { stderr.write('Input closed: nothing written.\n'); return 1; }
+    }
+    selected = withDependencies(selected);
+    // Recommended skills are downloaded before the plan, so a failed download writes nothing.
+    const remote = selected.filter(isRecommended);
+    let downloaded = [];
+    if (remote.length) {
+      stdout.write(`Downloading ${remote.join(', ')} from GitHub...\n`);
+      try { downloaded = await downloadRecommended(remote, { fetch: io.fetch ?? globalThis.fetch }); }
+      catch (error) {
+        if (!(error instanceof DownloadError)) throw error;
+        stderr.write(`Could not download the recommended skills (${remote.join(', ')}): ${error.message}\n`);
+        stderr.write('No files written. Try again later, or run the command without the recommended skill.\n');
+        return 1;
+      }
+    }
+    const plans = buildPlans({ target, roots, selected, source: io.source ?? repository, downloaded });
+    stdout.write(`${describePlans(target, plans, downloaded)}\n`);
+    const problems = blocking(plans);
+    if (problems.length) {
+      stderr.write(`\nInstallation stopped, no files changed:\n${problems.map(p => `  ${p}`).join('\n')}\n`);
+      stderr.write('Restore or move the listed files (or reselect the skill) and run the command again.\n');
+      return 1;
+    }
+    if (options.dryRun) { stdout.write('\nDry run: no files written.\n'); return 0; }
+    if (!interactive && !options.yes) {
+      stdout.write('\nNo terminal for confirmation: no files written. Add --yes to install this plan.\n');
+      return 0;
+    }
+    if (interactive) {
+      const answer = await reader.ask('\nInstall this plan? [y/N]: ');
+      if (!/^(y|yes|s|si|sì)$/i.test((answer ?? '').trim())) { stdout.write('Cancelled: no files written.\n'); return 0; }
+    }
+    for (const { plan } of plans) checkPlan(plan, target);
+    for (const { plan } of plans) applyPlan(plan);
+    stdout.write(`\nInstalled into ${plans.map(p => p.root).join(' and ')}.\n`);
+    return 0;
+  } catch (error) {
+    stderr.write(`${error instanceof UsageError ? 'Error' : 'Installation failed'}: ${error.message}\n`);
+    if (error instanceof UsageError) stderr.write('Run with --help for usage. No files written.\n');
+    return 1;
+  } finally {
+    reader?.close();
+  }
+}