@averildwi/nest-skills 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 averildwi
+
+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,100 @@
-# Temporary Holding Version
+# @averildwi/nest-skills
 
-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.
+Install Everill's NestJS + Prisma coding standards into a project as **agent skills**
+plus an **`AGENTS.md`** index, so AI coding agents (OpenCode, Claude Code) write code
+that follows the same rules as the rest of the team.
+
+It only writes Markdown. It never touches your code, `package.json` or `.env*`.
+
+```bash
+npx @averildwi/nest-skills --agent opencode
+```
+
+## Recommended order on a new project
+
+```bash
+npx @nestjs/cli@11 new my-app --strict
+cd my-app
+npx @averildwi/nest-prisma --db postgres     # client in generated/prisma (root)
+npx @averildwi/nest-common
+npx @averildwi/nest-skills --agent opencode   # or claude / both
+```
+
+Commit after each tool, on its own (see the `git-workflow` skill). The standard
+targets Nest 11 (CommonJS + Jest + ESLint); pin `@nestjs/cli@11` when creating
+the project.
+
+## What gets installed
+
+| Agent | Skills folder | Index | Extra |
+|---|---|---|---|
+| `opencode` | `.opencode/skills/<name>/SKILL.md` | `AGENTS.md` | |
+| `claude` | `.claude/skills/<name>/SKILL.md` | `AGENTS.md` | `CLAUDE.md` with `@AGENTS.md` |
+| `both` | `.claude/skills/<name>/SKILL.md` (OpenCode reads this folder too) | `AGENTS.md` | `CLAUDE.md` with `@AGENTS.md` |
+
+Plus `.nest-skills.json`, which records a hash of every file the tool wrote. Commit it.
+
+Skills:
+
+| Skill | Covers |
+|---|---|
+| `nest-architecture` | folder layout, layering, naming, `main.ts` order, `trust proxy`, Swagger prefixes |
+| `nest-response-and-errors` | response envelope, marker classes, exception filters and their order |
+| `nest-validation-and-config` | DTOs, `PaginationDto`, `ValidationPipe`, Joi env schema, `ConfigService` |
+| `nest-prisma` | ID type (asked first), `@@map`, timestamps, `select`, transactions, destructive commands |
+| `nest-auth-and-security` | JWT, guards, roles, scrypt hashing, OTP, throttling, CORS, `:id` pipes |
+| `nest-testing` | service unit tests with mocked Prisma and transactions |
+| `git-workflow` | branch, verify, stage specific files, Conventional Commits, local commits only |
+
+`AGENTS.md` maps tasks to skills, lists the global "never do" rules, and says how to
+behave when existing scaffold code differs from the standard.
+
+## Options
+
+```
+npx @averildwi/nest-skills [install] [options]
+npx @averildwi/nest-skills update [options]
+
+-a, --agent <name>   opencode | claude | both
+--dir <path>         install skills in another folder (relative, inside the project)
+--force              overwrite files you edited (old copy kept in .nest-skills-backup/)
+-y, --yes            no prompts, no confirmation
+--dry-run            show the plan only
+--no-color           plain output
+-v, --version        print the version
+-h, --help           show help
+```
+
+## Your files are safe
+
+- Your own **`AGENTS.md` / `CLAUDE.md`** (not written by nest-skills) are **never** overwritten,
+  not even with `--force`.
+  - Own `AGENTS.md`: the index goes to `AGENTS.nest-skills.md` and the CLI prints the line to add.
+  - Own `CLAUDE.md`: left as is; the CLI tells you to add `@AGENTS.md` (or the fallback name).
+- A skill file with the same name that you wrote yourself is kept; `--force` replaces it
+  and saves yours under `.nest-skills-backup/<timestamp>/`.
+- A file nest-skills wrote and **you edited** is kept by `install` and `update`.
+  `--force` replaces it and saves your version under `.nest-skills-backup/<timestamp>/`.
+  That folder sits outside the skills folder (the agent never loads a backup) and
+  contains its own `.gitignore`, so it is never committed by accident.
+- Running the command twice changes nothing.
+- CRLF vs LF does not count as an edit.
+
+## How it works
+
+The CLI follows the same pattern as `@averildwi/nest-common` and `@averildwi/nest-prisma`:
+a list of steps (`src/steps/*`), each with `plan(ctx)` (reads only) and `run(ctx, data)`.
+The full plan is printed first, then applied after confirmation (or `--yes`).
+
+See [docs/USAGE.md](docs/USAGE.md) for details and edge cases.
+
+## Development
+
+```bash
+npm install
+npm test        # node:test, unit + integration (spawns the real CLI in temp folders)
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+const { main } = require('../src/main');
+const { CliError, CancelledError } = require('../src/errors');
+const ui = require('../src/ui/output');
+
+main(process.argv.slice(2)).catch((err) => {
+    if (err instanceof CancelledError) {
+        ui.out();
+        ui.warn(err.message);
+        process.exit(err.exitCode);
+    }
+    if (err instanceof CliError) {
+        ui.error(err.failedStep ? `${err.failedStep} failed: ${err.message}` : err.message);
+        for (const h of err.hints) ui.hint(h);
+        process.stderr.write('\n');
+        process.exit(err.exitCode);
+    }
+    ui.error('Unexpected error. This is likely a bug in nest-skills.');
+    process.stderr.write(`${err && err.stack ? err.stack : err}\n\n`);
+    process.exit(1);
+});

package/docs/USAGE.md

@@ -0,0 +1,108 @@
+# Usage
+
+## 1. Install
+
+Run from the root of a NestJS project (a `package.json` that lists `@nestjs/core`).
+
+```bash
+npx @averildwi/nest-skills                  # asks which agent
+npx @averildwi/nest-skills --agent claude   # no question
+npx @averildwi/nest-skills --agent both --yes
+```
+
+Without a terminal (CI, scripts) or with `--yes`, `--agent` is required on the first install.
+Later runs read the agent and folder from `.nest-skills.json`.
+
+### Which agent?
+
+| Choose | When |
+|---|---|
+| `opencode` | Only OpenCode is used. Skills go to `.opencode/skills`. |
+| `claude` | Only Claude Code is used. Skills go to `.claude/skills`, plus a `CLAUDE.md` that imports `AGENTS.md`. |
+| `both` | The team uses both. One copy in `.claude/skills`, which OpenCode also reads. Installing into two folders would make OpenCode see every skill twice, and skill names must be unique. |
+
+Sources: OpenCode [skills](https://opencode.ai/docs/skills/) and [rules](https://opencode.ai/docs/rules/),
+Claude Code [skills](https://code.claude.com/docs/en/skills) and [memory](https://code.claude.com/docs/en/memory).
+Claude Code reads `AGENTS.md` by itself only when there is no `CLAUDE.md` and only on newer
+versions. The `@AGENTS.md` import in `CLAUDE.md` works in every case.
+
+### Custom folder
+
+```bash
+npx @averildwi/nest-skills --agent opencode --dir .agents/skills
+```
+
+`AGENTS.md` is rendered with the folder you choose, so the agent is told the real path.
+The folder must be relative and inside the project.
+
+## 2. Commit
+
+```bash
+git switch -c chore/agent-skills
+git add AGENTS.md .opencode/skills .nest-skills.json      # adjust to the printed list
+git commit -m "chore: add agent skills"
+```
+
+Commit generated files on their own, before you edit anything (`git-workflow` rule 6).
+
+## 3. Update to a newer version
+
+```bash
+npx @averildwi/nest-skills@latest update --dry-run   # see what would change
+npx @averildwi/nest-skills@latest update
+```
+
+| File state | `install` | `update` | with `--force` |
+|---|---|---|---|
+| missing | created | created | created |
+| same as bundled | skipped | skipped | skipped |
+| written by us, unedited, older | reported ("run update") | **refreshed** | refreshed |
+| written by us, **edited by you** | kept | kept | replaced, your copy backed up |
+| **not written by us**: a skill file | kept | kept | replaced, your copy backed up |
+| **not written by us**: `AGENTS.md` / `CLAUDE.md` | kept | kept | **kept** |
+
+Backups go to `.nest-skills-backup/<timestamp>/<original path>`, never next to the skill
+(a stray `SKILL.md.bak` inside the skills folder would be committed with `git add <skillsDir>`).
+The backup folder contains a `.gitignore` with `*`, so git ignores it without any change to
+your own `.gitignore`. Delete it when you no longer need the copies.
+
+"Written by us" means the path and its hash are in `.nest-skills.json`. If you delete that
+file, every installed file counts as yours and will not be updated.
+
+## 4. Switching agent
+
+```bash
+npx @averildwi/nest-skills --agent claude
+```
+
+`AGENTS.md` (if unedited) is rewritten to point at the new folder and `CLAUDE.md` is added.
+The old skills folder is **not deleted**; the CLI prints the `git rm -r` command to run.
+
+## 5. When you already have AGENTS.md or CLAUDE.md
+
+- Own `AGENTS.md`: kept. The index is written to `AGENTS.nest-skills.md`. Add a line to your
+  `AGENTS.md` such as `Read AGENTS.nest-skills.md before writing NestJS code and follow it.`
+- Own `CLAUDE.md`: kept. Add `@AGENTS.md` (or `@AGENTS.nest-skills.md`) as its first line.
+  If it already has that line, nothing is reported.
+
+## 6. Existing scaffold code that differs from the skills
+
+The skills describe the target standard. Code generated by older `nest-common`/`nest-prisma`
+versions may differ (optional `page?` in `PaginationDto`, `string[]` roles, `any` in
+interceptors, CORS `'*'`, no Jest `moduleNameMapper`). The section
+"When the existing code differs from these skills" in `AGENTS.md` tells the agent to adapt
+at the call site, not rewrite shared code silently, and to propose a separate commit.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | done, or nothing to do |
+| 1 | not a NestJS project, invalid `package.json` / `.nest-skills.json`, write error |
+| 2 | bad arguments, `--agent` missing in non-interactive mode, `update` without an install |
+| 130 | cancelled |
+
+## Not included (ideas)
+
+- `--with-commitlint`: decision N5 is "not yet", and it would have to edit `package.json`,
+  which this tool never does. Left out on purpose.

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@averildwi/nest-skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Install Everill's NestJS + Prisma coding standards as agent skills (OpenCode / Claude Code) plus an AGENTS.md index.",
+  "main": "bin/cli.js",
+  "bin": {
+    "nest-skills": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "docs"
+  ],
+  "scripts": {
+    "test": "node --test test/unit.test.js test/integration.test.js"
+  },
+  "keywords": [
+    "nestjs",
+    "prisma",
+    "agent-skills",
+    "agents-md",
+    "opencode",
+    "claude-code",
+    "cli"
+  ],
+  "author": "averildwi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/averildwi/nest-skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/averildwi/nest-skills/issues"
+  },
+  "homepage": "https://github.com/averildwi/nest-skills#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "type": "commonjs",
+  "dependencies": {
+    "inquirer": "^9.0.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,124 @@
+const { parseArgs } = require('util');
+
+const { CliError } = require('./errors');
+const { AGENTS, BACKUP_DIR } = require('./config/agents');
+
+const COMMANDS = ['install', 'update'];
+
+const OPTIONS = {
+    help: { type: 'boolean', short: 'h' },
+    version: { type: 'boolean', short: 'v' },
+    yes: { type: 'boolean', short: 'y' },
+    'dry-run': { type: 'boolean' },
+    force: { type: 'boolean' },
+    agent: { type: 'string', short: 'a' },
+    dir: { type: 'string' },
+    color: { type: 'boolean' },
+    'no-color': { type: 'boolean' },
+};
+
+/**
+ * Parses argv into a normalised options object. Unspecified options stay
+ * `undefined` so the caller can prompt or fall back to the manifest.
+ */
+function parseCliArgs(argv = process.argv.slice(2)) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
+    } catch (err) {
+        throw new CliError(err.message.replace(/\. To specify.*$/s, '.'), {
+            hints: ['Run "nest-skills --help" to see all available options.'],
+            exitCode: 2,
+        });
+    }
+
+    const v = parsed.values;
+    const [command = 'install', ...extra] = parsed.positionals;
+    if (!COMMANDS.includes(command)) {
+        throw new CliError(`Unknown command "${command}".`, {
+            hints: [`Supported commands: ${COMMANDS.join(', ')}.`],
+            exitCode: 2,
+        });
+    }
+    if (extra.length) {
+        throw new CliError(`Unexpected argument "${extra[0]}".`, { exitCode: 2 });
+    }
+
+    let agent;
+    if (v.agent !== undefined) {
+        agent = v.agent.toLowerCase();
+        if (!AGENTS[agent]) {
+            throw new CliError(`Unknown agent "${v.agent}".`, {
+                hints: [`Supported values: ${Object.keys(AGENTS).join(', ')}.`],
+                exitCode: 2,
+            });
+        }
+    }
+
+    let dir;
+    if (v.dir !== undefined) {
+        dir = v.dir.trim().replace(/\\/g, '/').replace(/\/{2,}/g, '/').replace(/^(\.\/)+/, '').replace(/\/+$/, '');
+        const segments = dir.split('/');
+        // "." would put the skill folders straight into the project root, next to src/.
+        const unsafe =
+            !dir ||
+            dir.startsWith('/') ||
+            /^[a-z]:/i.test(dir) ||
+            segments.some((s) => s === '.' || s === '..') ||
+            segments[0] === BACKUP_DIR ||
+            segments[0] === 'node_modules';
+        if (unsafe) {
+            throw new CliError(`Invalid --dir "${v.dir}".`, {
+                hints: ['Use a sub-folder of the project root, e.g. --dir .agents/skills'],
+                exitCode: 2,
+            });
+        }
+    }
+
+    return {
+        command,
+        help: Boolean(v.help),
+        version: Boolean(v.version),
+        yes: Boolean(v.yes),
+        dryRun: Boolean(v['dry-run']),
+        force: Boolean(v.force),
+        agent,
+        dir,
+        color: v['no-color'] ? false : v.color ? true : undefined,
+    };
+}
+
+function helpText(pkg) {
+    return `
+  ${pkg.name} v${pkg.version}
+  Install the NestJS + Prisma coding standards as agent skills and an AGENTS.md index.
+
+  Usage
+    $ npx ${pkg.name} [install] [options]
+    $ npx ${pkg.name} update [options]
+
+  Commands
+    install            Add missing skills and the index (default). Never overwrites your edits.
+    update             Also refresh files you have not edited to the bundled version.
+
+  Options
+    -a, --agent <name> opencode | claude | both (update: default from .nest-skills.json)
+                         opencode -> .opencode/skills + AGENTS.md
+                         claude   -> .claude/skills + AGENTS.md + CLAUDE.md (imports AGENTS.md)
+                         both     -> .claude/skills (read by both tools) + AGENTS.md + CLAUDE.md
+    --dir <path>       Install skills somewhere else (relative to the project root)
+    --force            Overwrite files you edited or wrote yourself (old copy kept in .nest-skills-backup/)
+    -y, --yes          Skip prompts and the confirmation
+    --dry-run          Show the plan without writing anything
+    --no-color         Disable coloured output
+    -v, --version      Print the version
+    -h, --help         Show this help
+
+  Examples
+    $ npx ${pkg.name} --agent opencode
+    $ npx ${pkg.name} --agent both --yes
+    $ npx ${pkg.name} update --dry-run
+`;
+}
+
+module.exports = { parseCliArgs, helpText, COMMANDS };

package/src/config/agents.js

@@ -0,0 +1,49 @@
+/**
+ * Where each agent reads skills and project instructions.
+ *
+ * Sources (checked 2026-10-13):
+ * - OpenCode, https://opencode.ai/docs/skills/ : project skills in
+ *   `.opencode/skills/<name>/SKILL.md`, `.claude/skills/<name>/SKILL.md` or
+ *   `.agents/skills/<name>/SKILL.md`; names must be unique across locations.
+ * - OpenCode, https://opencode.ai/docs/rules/ : project rules in `AGENTS.md`
+ *   at the project root; `CLAUDE.md` is only a fallback when AGENTS.md is absent.
+ * - Claude Code, https://code.claude.com/docs/en/skills : project skills in
+ *   `.claude/skills/<name>/SKILL.md`.
+ * - Claude Code, https://code.claude.com/docs/en/memory : reads `AGENTS.md`
+ *   only when there is no `CLAUDE.md` (and only from v2.1.277); a `CLAUDE.md`
+ *   that contains `@AGENTS.md` works in every version and setting.
+ *
+ * "both" installs one copy in `.claude/skills`, which both tools read, so the
+ * same skill name never appears twice for OpenCode.
+ */
+const AGENTS = {
+    opencode: {
+        value: 'opencode',
+        label: 'OpenCode',
+        skillsDir: '.opencode/skills',
+        claudeMd: false,
+    },
+    claude: {
+        value: 'claude',
+        label: 'Claude Code',
+        skillsDir: '.claude/skills',
+        claudeMd: true,
+    },
+    both: {
+        value: 'both',
+        label: 'OpenCode + Claude Code',
+        skillsDir: '.claude/skills',
+        claudeMd: true,
+    },
+};
+
+/** Fallback index name when the project already has its own AGENTS.md. */
+const FALLBACK_INDEX = 'AGENTS.nest-skills.md';
+const MANIFEST_FILE = '.nest-skills.json';
+/**
+ * --force keeps the replaced file here, outside the skills folder, so the
+ * printed `git add <skillsDir>` never stages a backup and OpenCode never sees one.
+ */
+const BACKUP_DIR = '.nest-skills-backup';
+
+module.exports = { AGENTS, FALLBACK_INDEX, MANIFEST_FILE, BACKUP_DIR };

package/src/errors.js

@@ -0,0 +1,27 @@
+/**
+ * An expected, user-facing failure. Rendered by the entrypoint as a clean
+ * message plus hints instead of a stack trace.
+ */
+class CliError extends Error {
+    /**
+     * @param {string} message
+     * @param {{ hints?: string[], exitCode?: number, cause?: unknown }} [options]
+     */
+    constructor(message, { hints = [], exitCode = 1, cause } = {}) {
+        super(message);
+        this.name = 'CliError';
+        this.hints = hints;
+        this.exitCode = exitCode;
+        if (cause) this.cause = cause;
+    }
+}
+
+/** Raised when the user aborts (Ctrl+C or answering "no" to the confirmation). */
+class CancelledError extends CliError {
+    constructor(message = 'Cancelled. No changes were made.') {
+        super(message, { exitCode: 130 });
+        this.name = 'CancelledError';
+    }
+}
+
+module.exports = { CliError, CancelledError };

package/src/main.js

@@ -0,0 +1,54 @@
+const pkg = require('../package.json');
+const { parseCliArgs, helpText } = require('./cli');
+const { setColorEnabled } = require('./ui/colors');
+const ui = require('./ui/output');
+const { runPreflight } = require('./preflight');
+const { resolveAgent, confirmPlan } = require('./prompts');
+const { readManifest } = require('./utils/manifest');
+const runner = require('./runner');
+
+async function main(argv, { cwd = process.cwd(), isTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY) } = {}) {
+    const options = parseCliArgs(argv);
+    if (options.color !== undefined) setColorEnabled(options.color);
+
+    if (options.help) {
+        process.stdout.write(helpText(pkg));
+        return;
+    }
+    if (options.version) {
+        process.stdout.write(`${pkg.version}\n`);
+        return;
+    }
+
+    const interactive = isTTY && !options.yes;
+    ui.header('nest-skills', `v${pkg.version}`);
+
+    runPreflight(cwd);
+    const manifest = readManifest(cwd);
+    const agent = await resolveAgent(options, { interactive, manifest });
+
+    const ctx = runner.buildContext({ projectRoot: cwd, pkg, options, agent, manifest });
+    const plan = await runner.buildPlan(ctx);
+    runner.printPlan(ctx, plan, { dryRun: options.dryRun });
+
+    if (!plan.some((p) => p.actionable)) {
+        ui.out();
+        ui.success('Everything is already installed. Nothing to do.');
+        runner.printSummary(ctx, plan, { files: [] });
+        return;
+    }
+    if (options.dryRun) {
+        ui.out();
+        ui.info('Dry run complete. Re-run without --dry-run to apply these changes.');
+        ui.out();
+        return;
+    }
+
+    ui.out();
+    if (interactive) await confirmPlan();
+
+    const summary = await runner.executePlan(ctx, plan);
+    runner.printSummary(ctx, plan, summary);
+}
+
+module.exports = { main };

package/src/preflight.js

@@ -0,0 +1,35 @@
+const fs = require('fs');
+const path = require('path');
+
+const { CliError } = require('./errors');
+
+function readPackageJson(projectRoot) {
+    const file = path.join(projectRoot, 'package.json');
+    if (!fs.existsSync(file)) {
+        throw new CliError('No package.json found in the current directory.', {
+            hints: [`Current directory: ${projectRoot}`, 'Run this command from the root of your NestJS project.'],
+        });
+    }
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch (err) {
+        throw new CliError('package.json is not valid JSON.', { hints: [err.message], cause: err });
+    }
+}
+
+/** Validates that the current directory is a NestJS project. Reads only package.json. */
+function runPreflight(projectRoot) {
+    const pkgJson = readPackageJson(projectRoot);
+    const deps = { ...pkgJson.dependencies, ...pkgJson.devDependencies };
+    if (!deps['@nestjs/core']) {
+        throw new CliError("This doesn't look like a NestJS project.", {
+            hints: [
+                'package.json does not list @nestjs/core.',
+                'Create one first with: npx @nestjs/cli new my-app',
+            ],
+        });
+    }
+    return { pkgJson };
+}
+
+module.exports = { runPreflight, readPackageJson };

package/src/prompts.js

@@ -0,0 +1,59 @@
+const { CancelledError, CliError } = require('./errors');
+const { AGENTS } = require('./config/agents');
+
+async function prompt(questions) {
+    // inquirer 9 is ESM-only, so it has to be loaded with a dynamic import.
+    const { default: inquirer } = await import('inquirer');
+    try {
+        return await inquirer.prompt(questions);
+    } catch (err) {
+        if (err && (err.name === 'ExitPromptError' || /force closed/i.test(err.message || ''))) {
+            throw new CancelledError();
+        }
+        throw err;
+    }
+}
+
+/**
+ * Decides the agent target. Priority: --agent, then the manifest of a previous
+ * install, then a prompt. Without a TTY (or with --yes) there is no prompt.
+ */
+async function resolveAgent(options, { interactive, manifest }) {
+    if (options.agent) return options.agent;
+    if (manifest && AGENTS[manifest.agent]) return manifest.agent;
+
+    if (options.command === 'update') {
+        throw new CliError('No previous install found (.nest-skills.json is missing).', {
+            hints: ['Run "npx @averildwi/nest-skills --agent <opencode|claude|both>" first.'],
+            exitCode: 2,
+        });
+    }
+    if (!interactive) {
+        throw new CliError('Choose an agent with --agent when running non-interactively.', {
+            hints: [
+                `Supported values: ${Object.keys(AGENTS).join(', ')}.`,
+                'Example: npx @averildwi/nest-skills --agent opencode --yes',
+            ],
+            exitCode: 2,
+        });
+    }
+
+    const { agent } = await prompt([
+        {
+            type: 'list',
+            name: 'agent',
+            message: 'Which AI agent should read these skills?',
+            choices: Object.values(AGENTS).map((a) => ({ name: `${a.label}  (${a.skillsDir})`, value: a.value })),
+        },
+    ]);
+    return agent;
+}
+
+async function confirmPlan() {
+    const { proceed } = await prompt([
+        { type: 'confirm', name: 'proceed', message: 'Apply these changes?', default: true },
+    ]);
+    if (!proceed) throw new CancelledError();
+}
+
+module.exports = { resolveAgent, confirmPlan };