Specgen Ts Cli

---
name: specgen-ts-cli
model: claude-opus-4-6
effort: high
description: >
  Generate a detailed specification document for building a distributable Node.js CLI
  application written in TypeScript. Uses Commander.js for command parsing, tsup for
  bundling, and @yao-pkg/pkg for cross-platform binary packaging (Windows, macOS, Linux).
  Interactive prompts (Inquirer.js), persistent user config (conf), project-level config
  (cosmiconfig), shell execution (execa), HTTP client (got), plugin system, and
  auto-update checking are configurable based on application needs.
  Standardized input: application name (mandatory), version (mandatory), command (optional).
  Use this skill whenever the user asks to create a spec, specification, blueprint, or
  technical design document for a new CLI tool, command-line application, terminal tool,
  or developer tool. Also trigger when the user says things like "spec out a new CLI",
  "design a TypeScript CLI", "write a technical spec for my CLI tool",
  "scaffold spec for a Node CLI", or any request describing a command-line application.
  Even if the user only mentions a subset (e.g., "CLI with config file support" or
  "distributable Node tool"), this skill likely applies — ask and confirm.
---

# TypeScript CLI Application Specification Generator

This skill generates a comprehensive specification document (Markdown) that serves as a
blueprint for building a distributable Node.js CLI application in TypeScript. The spec is
intended to be followed by a developer or coding agent to produce a fully functional,
packageable CLI tool.

The specification does NOT generate code. It produces a detailed, opinionated technical
document describing every layer of the application — from `package.json` configuration to
command action handlers to binary packaging — so that implementation becomes a mechanical
exercise.

## Technology Stack

### Core Stack (Always Included)

These are the fixed versions the spec targets. Do not deviate unless the user explicitly
requests different versions.

| Component       | Version  |
|-----------------|----------|
| Node.js         | 22.x LTS |
| TypeScript      | 5.x      |
| Commander.js    | 12.x     |
| tsup            | 8.x      |
| Zod             | 3.x      |
| Chalk           | 5.x      |
| Ora             | 8.x      |

> **Note:** Chalk 5.x and Ora 8.x are ESM-only packages. The project uses
> `"type": "module"` in `package.json` and targets ESM output from tsup.
> All imports use the `.js` extension suffix even for TypeScript source files.

### Optional Integration Versions

Include in the version table only when the corresponding integration is selected.

| Component              | Version | When Selected           |
|------------------------|---------|-------------------------|
| @inquirer/prompts      | 7.x     | Prompts = yes           |
| conf                   | 13.x    | User Config = yes       |
| cosmiconfig            | 9.x     | Project Config = yes    |
| better-sqlite3         | 11.x    | Local Database = yes    |
| drizzle-orm            | 0.36.x  | Local Database = yes    |
| env-paths              | 3.x     | Local Database = yes    |
| drizzle-kit            | 0.28.x  | Local Database = yes (dev) |
| execa                  | 9.x     | Shell Execution = yes   |
| got                    | 14.x    | HTTP Client = yes       |
| update-notifier        | 7.x     | Auto-update = yes       |
| @yao-pkg/pkg           | 5.x     | Binary Packaging = yes  |
| cli-table3             | 0.6.x   | Table Output = yes      |
| boxen                  | 8.x     | Banner/Box UI = yes     |
| glob                   | 11.x    | File Operations = yes   |

> **Async patterns (Polling, Inline Batch, Background Daemon) use no additional
> npm packages** — they are implemented entirely with Node.js built-ins
> (`setTimeout`, `process.kill`, `child_process.spawn`) and the packages already
> in the core stack (ora for progress, chalk for output). The async pattern type
> is detected from PRD.md NFRs and user stories; no new dependency version rows
> are needed.

## Core Dependencies (package.json)

The spec must include these in the `dependencies` configuration section (always):

- `commander` — CLI argument parsing and command routing
- `chalk` — Terminal colour output (ESM-only, v5+)
- `ora` — Spinner / progress indicators
- `zod` — Schema validation for config, arguments, and API payloads

Always in `devDependencies`:
- `typescript` — TypeScript compiler
- `tsup` — TypeScript bundler (esbuild-based, handles ESM, shebang injection)
- `vitest` — Unit and integration testing
- `@types/node` — Node.js type declarations
- `tsx` — TypeScript execution for scripts and development
- `eslint` + `@typescript-eslint/eslint-plugin` — Linting

### Conditional Dependencies

**If Prompts = yes:**
- `@inquirer/prompts` — Modern interactive prompts (officially maintained Inquirer v9+)

**If User Config = yes:**
- `conf` — Persistent user-level configuration stored in OS config directory

**If Project Config = yes:**
- `cosmiconfig` — Project-level config file loading (supports `.json`, `.yaml`, `.js`, `package.json`)

**If Local Database = yes:**
- `better-sqlite3` — Synchronous SQLite driver (no async complexity in CLI context)
- `drizzle-orm` — TypeScript-first ORM with schema-as-code and type-safe query builder
- `env-paths` — OS-correct data directory resolution (macOS / Linux / Windows)
- `@types/better-sqlite3` — TypeScript type declarations (devDependency)
- `drizzle-kit` — Migration generator and Drizzle Studio (devDependency)

**If Shell Execution = yes:**
- `execa` — Child process execution with better ergonomics and ESM support

**If HTTP Client = yes:**
- `got` — HTTP client with TypeScript-first design (ESM-only, v14+)

**If Auto-update = yes:**
- `update-notifier` — Non-blocking update checks against npm registry

**If Binary Packaging = yes (devDependency):**
- `@yao-pkg/pkg` — Compiles Node.js application into standalone executables

**If Table Output = yes:**
- `cli-table3` — Tabular terminal output with borders and alignment

**If Banner/Box UI = yes:**
- `boxen` — Bordered terminal box output (ESM-only)

**If File Operations = yes:**
- `glob` — File system globbing with ESM support

## When the Skill Triggers

Generate the spec when the user provides an **application name** and **version** that
corresponds to one of the custom applications defined in `CLAUDE.md`. The skill
reads all required inputs from the project's context files — no interactive Q&A is needed
for the core inputs.

The user invokes this skill by specifying the target application and version, for example:
- `/specgen-ts-cli my_tool v0.1.0`
- `/specgen-ts-cli my_tool v0.1.0 command:deploy`
- `/specgen-ts-cli "My Tool" v0.1.0`

The skill then locates the matching context folder and reads all input files automatically.

## Version Gate

Before starting any work, resolve the application folder first (see Input Resolution below), then check `CHANGELOG.md` in the application folder (`<app_folder>/CHANGELOG.md`):

1. If `<app_folder>/CHANGELOG.md` does not exist, skip this check (first-ever execution for this application).
2. If `<app_folder>/CHANGELOG.md` exists, scan all `## vX.Y.Z` headings and determine the **highest version** using semantic versioning comparison.
3. Compare the requested version against the highest version:
   - If requested version **>=** highest version: proceed normally.
   - If requested version **<** highest version: **STOP immediately**. Print: `"Version {requested} is lower than the current application version {highest} recorded in <app_folder>/CHANGELOG.md. Execution rejected."` Do NOT proceed with any work.

## Input Resolution

This skill uses standardized input resolution. Provide:

| Argument          | Required | Example           | Description                                 |
|-------------------|----------|-------------------|---------------------------------------------|
| `<application>`   | Yes      | `my_tool`         | Application name to locate the context folder |
| `<version>`       | Yes      | `v0.1.0`          | Version to scope processing                 |
| `command:<name>`  | No       | `command:deploy`  | Limit generation to a single command spec   |

### Application Folder Resolution

The application name is matched against root-level application folders:
1. Strip any leading `<number>_` prefix from folder names (e.g., `1_my_tool` → `my_tool`)
2. Match case-insensitively against the provided application name
3. Accept snake_case, kebab-case, or title-case input (all match the same folder)
4. If no match found, list available applications and stop

### Auto-Resolved Paths

| File           | Resolved Path                          |
|----------------|----------------------------------------|
| PRD.md         | `<app_folder>/context/PRD.md`          |
| Command Models | `<app_folder>/context/model/`          |
| Output         | `<app_folder>/context/specification/`  |

### Version Filtering

When a version is provided, only include user stories, NFRs, and constraints from versions
<= the provided version. For example, if `v0.3.0` is specified:
- Include items tagged `[v0.1.0]`, `[v0.2.0]`, `[v0.3.0]`
- Exclude items tagged `[v0.4.0]` or later
- Version comparison uses semantic versioning order

### Command Filtering

When `command:<name>` is provided:
- Only generate the `SPEC.md` for that specific command
- Other existing command spec files remain untouched
- `SPECIFICATION.md` (root) gets a partial update — only that command's TOC entry is
  added or updated; all other entries are preserved as-is

## Gathering Input

The specification is driven by **four input sources** read from the project's context files.
The skill does NOT ask the user for prompts, config, packaging, or other choices — it
**determines** these automatically from the context.

### Input 1: Application Name (from CLAUDE.md)

From CLAUDE.md (already loaded in context), locate the target application under the
**Custom Applications** section. Extract:

- **Application name**: The section heading (e.g., "My Tool", "Deploy CLI")
- **Binary name**: The kebab-case executable name (e.g., `my-tool`, `deploy`)
- **Application description**: The description paragraph below the heading
- **Target audiences**: The "Used by" or "Consumers" list
- **Dependencies**: The "Depends on" list — primary source for determining optional components

The application name is used to derive:
- **Package name**: kebab-case of the application name with `@scope/` prefix if scoped
- **Binary name**: The `bin` entry in `package.json`
- **Main TypeScript namespace**: PascalCase (e.g., `MyTool`)

### Input 2: User Stories (from PRD.md)

Read `<app_folder>/context/PRD.md`. This file contains all user stories organized by
command. Extract:

- **Commands**: Each `## Command: <name>` or `### <CommandName>` section
- **User stories per command**: Tagged items like `[USCLI00101] As a user, I want to...`
  These define the functional requirements for each command's action handler and prompts

The user stories directly inform:
- Which arguments and options each command exposes
- What interactive prompts are shown (if any)
- What output the command produces (table, JSON, plain text)
- Which service methods are called

**Important:** Items with strikethrough (`~~text~~`) are deprecated. List them in the
"Removed / Replaced" subsection of the traceability table. Carry version tags through
to the generated specification's traceability section.

### Input 3: Non-Functional Requirements (from PRD.md)

Within the same `PRD.md`, each command has a `### Non Functional Requirement` section
with tagged items like `[NFRCLI0120]`. These inform:

- Output format requirements (JSON, table, plain text, `--output` flag)
- Performance constraints (timeout, caching)
- Security requirements (credential storage, token handling)
- Platform constraints (Windows compatibility, PATH requirements)

### Input 4: Command Model (from model/ folder)

Read `<app_folder>/context/model/MODEL.md` first as the index, then read the individual
command model files in each command subfolder.

**MODEL.md** provides:
- Summary table of all commands with argument/option counts
- Links to each command's detailed model files

**Per-command files** (e.g., `model/deploy/model.md`):
- Complete argument definitions with types and descriptions
- Option definitions with flags, types, defaults
- Config keys read or written by this command
- External services or APIs called

The command model directly maps to:
- `Command` argument and option declarations in Commander.js
- Zod schemas for config validation
- Service interface method signatures
- `--help` text content

## PRD.md Extended Sections

Before determining optional components, check PRD.md for the following extended sections:

### Architecture Principle Extraction

If PRD.md contains an `# Architecture Principle` section, extract patterns that affect CLI decisions:

| Pattern to Extract | How It Influences the Specification |
|---|---|
| "Container based deployment" | Include Dockerfile section; favor environment variables over config files |
| "Event-driven" | CLI may need webhook listeners or polling patterns |
| Async patterns (polling, batch, daemon) | Inform command handler async strategies |

If the section is absent, proceed with existing detection.

### High Level Process Flow Extraction

If PRD.md contains a `# High Level Process Flow` section:
1. Process flows describing CLI-initiated operations inform command action handler sequences
2. Each flow step can emit a spinner/progress update
3. Error handling chains follow the flow's error paths

If the section is absent, derive command flow from user stories only (existing behavior).

---

## Determining Optional Components

Instead of asking the user, the skill determines optional components by analyzing the
dependencies and requirements in `CLAUDE.md` and cross-referencing with `PRD.md` NFRs.

### Prompts Detection

| Content Pattern | Prompts Selection |
|---|---|
| NFRs mention "interactive", "ask user", "prompt for", "wizard" | Prompts = yes |
| User stories describe `--interactive` mode or guided setup | Prompts = yes |
| User stories describe `init`, `setup`, `configure` commands | Prompts = yes |
| All inputs are non-interactive flags | Prompts = no |

### User Config Detection

| Content Pattern | User Config Selection |
|---|---|
| NFRs mention "remember", "save preference", "user setting", "persist" | User Config = yes |
| Commands like `config set`, `config get`, `login`, `logout` exist | User Config = yes |
| NFRs mention "API key", "token storage", "credential" | User Config = yes |
| No persistent state needed | User Config = no |

### Project Config Detection

| Content Pattern | Project Config Selection |
|---|---|
| NFRs mention "project configuration", "workspace config", "per-project" | Project Config = yes |
| A config file like `.mytoolrc`, `mytool.config.js`, or `package.json#mytool` is referenced | Project Config = yes |
| Tool operates at project/workspace level | Project Config = yes |
| Tool is purely global/user-scoped | Project Config = no |

### Local Database Detection

| Content Pattern | Local Database Selection |
|---|---|
| NFRs mention "run history", "execution log", "audit trail", "activity log" | Local Database = yes |
| NFRs mention "cache", "local cache", "offline", "sync state", "last sync" | Local Database = yes |
| User stories describe `history`, `log`, `list runs`, `show recent` commands | Local Database = yes |
| User stories describe tracking multiple entities of the same type locally | Local Database = yes |
| NFRs mention "retain for X days", "auto-prune", "retention policy" | Local Database = yes |
| Data needs filtering, sorting, or aggregation beyond a simple list | Local Database = yes |
| All persistent data fits in simple key-value pairs (use `conf` instead) | Local Database = no |

> **Local Database vs `conf`:** If the data has multiple rows, grows over time, needs
> querying, or involves relationships — use SQLite. If it is a handful of user
> preferences or a single token — use `conf`.

### Shell Execution Detection

| Content Pattern | Shell Execution Selection |
|---|---|
| NFRs mention "run command", "execute", "spawn", "shell", "subprocess" | Shell Execution = yes |
| Commands orchestrate other CLI tools (git, docker, npm, etc.) | Shell Execution = yes |
| Build/deploy commands that invoke external binaries | Shell Execution = yes |

### HTTP Client Detection

| Content Pattern | HTTP Client Selection |
|---|---|
| CLAUDE.md "Depends on" references any REST API or web service | HTTP Client = yes |
| NFRs mention "API call", "webhook", "REST", "HTTP", "fetch" | HTTP Client = yes |
| Commands interact with cloud providers, registries, or dashboards | HTTP Client = yes |

### Auto-Update Detection

| Content Pattern | Auto-Update Selection |
|---|---|
| NFRs mention "notify of updates", "check for new version", "self-update" | Auto-update = yes |
| Application is distributed via npm or GitHub releases | Auto-update = yes (default) |
| Internal tool used only within a controlled environment | Auto-update = no |

### Binary Packaging Detection

| Content Pattern | Binary Packaging Selection |
|---|---|
| CLAUDE.md mentions "standalone binary", "no Node.js required", "self-contained" | Binary Packaging = yes |
| Target users are unlikely to have Node.js installed | Binary Packaging = yes |
| Distribution via GitHub releases, Homebrew, or Chocolatey is mentioned | Binary Packaging = yes |
| Published to npm for developer toolchain use | Binary Packaging = no (npm distribution only) |

### Async Pattern Detection

Three sub-types are detected independently. A single application may use more than one.

#### Polling Detection

| Content Pattern | Polling Selection |
|---|---|
| User stories describe `--watch`, `--follow`, `--wait`, `--poll` flags | Polling = yes |
| NFRs say "wait until complete", "follow progress", "tail status" | Polling = yes |
| Commands trigger async operations that have a terminal state (success/failed) | Polling = yes |
| All operations complete synchronously within the API call | Polling = no |

#### Inline Batch Detection

| Content Pattern | Inline Batch Selection |
|---|---|
| User stories describe processing "all records", "all items", "bulk import/export" | Inline Batch = yes |
| NFRs mention `--concurrency`, parallel processing, rate limiting | Inline Batch = yes |
| Commands iterate over a potentially large collection (files, API resources, DB rows) | Inline Batch = yes |
| NFRs mention "skip errors", "continue on failure", "bail on first error" | Inline Batch = yes |
| NFRs mention "resume", "checkpoint", "skip already processed" | Inline Batch = yes (+ Local Database) |
| Processing is always a single item | Inline Batch = no |

#### Background Daemon Detection

| Content Pattern | Background Daemon Selection |
|---|---|
| User stories describe `daemon start`, `daemon stop`, `daemon status` commands | Background Daemon = yes |
| NFRs mention "background process", "persistent watcher", "always-on agent" | Background Daemon = yes |
| User stories describe a `worker` or `watcher` sub-command group | Background Daemon = yes |
| NFRs mention "detach", "run in background", "PID file" | Background Daemon = yes |
| All operations complete within a single command invocation | Background Daemon = no |

> **Async pattern vs User Config:** Any application with a Background Daemon also
> requires User Config = yes (to store the PID). The skill must force this
> dependency automatically when Background Daemon is detected.

### Table Output Detection

| Content Pattern | Table Output Selection |
|---|---|
| Commands produce list output (resources, records, results) | Table Output = yes |
| NFRs mention "tabular", "list view", "columns" | Table Output = yes |

### Summary of Determination

After analyzing all inputs, produce a determination summary before generating the spec:

```
Optional Component Determination:
- Prompts:              yes (from PRD.md → init command has interactive wizard)
- User Config:          yes (from PRD.md → login command stores API token)
- Project Config:       yes (from PRD.md → per-project .mytoolrc support)
- Local Database:       yes (from PRD.md → history command lists past runs)
- Async - Polling:      yes (from PRD.md → deploy --watch flag)
- Async - Inline Batch: yes (from PRD.md → sync --all processes 1000s of items)
- Async - Daemon:       no
- Shell Execution:      no
- HTTP Client:          yes (from CLAUDE.md → depends on My API)
- Auto-update:          yes (default for npm-distributed tool)
- Binary Packaging:     no (npm distribution only)
- Table Output:         yes (from PRD.md → list commands produce tabular output)
- Banner/Box UI:        no
- File Operations:      no
```

If the user disagrees with any determination, allow them to override before proceeding.

## Generating the Specification

Once inputs are gathered and optional components are determined, generate the specification
as a **multi-file output split by command**. Read the spec template at
`references/spec-template.md` for the exact structure and content of each section.
The template is the authoritative guide — follow it closely.

The specification is split into two categories:

1. **Root `SPECIFICATION.md`** — Shared infrastructure: `package.json`, TypeScript config,
   build tooling, CLI entry point, shared services, UI utilities, config management,
   error handling, testing strategy, and packaging.
2. **Per-command `<command-name>/SPEC.md`** — Each command gets its own folder with a
   self-contained specification covering argument/option definitions, service methods,
   prompt flows, and output formatting.

**Important:** The generated spec must use **real application data** from the context files:

- **Commands** must use the actual command names from PRD.md (e.g., `init`, `deploy`, `status`)
- **Arguments and options** must match the actual definitions in `model/<command>/model.md`
- **Service methods** must map to the actual user stories
- **Config keys** must match what the model defines
- **Version tags** on every user story ID, NFR ID, constraint ID
- **Removed / Replaced items** listed for deprecated items

### Output Structure

```
<app_folder>/context/specification/
├── SPECIFICATION.md              ← Shared infrastructure + TOC
├── init/
│   └── SPEC.md                   ← Command blueprint for 'init'
├── deploy/
│   └── SPEC.md                   ← Command blueprint for 'deploy'
├── config/
│   └── SPEC.md                   ← Command blueprint for 'config'
└── ...                           ← One folder per command from PRD.md
```

### What Goes in `SPECIFICATION.md` (Root)

#### 1. Project Overview
Application metadata, description, tech stack summary, binary name, target platforms,
the complete command list, and distribution strategy.

#### 2. package.json Configuration
Complete `package.json` with `"type": "module"`, `bin` entry, `files`, `engines`,
all runtime dependencies (core + selected conditional), all `devDependencies`, and `scripts`
(dev, build, typecheck, test, lint, plus platform-specific pkg scripts if Binary Packaging = yes).

#### 3. TypeScript & Build Configuration
Complete `tsconfig.json` targeting ESM. Complete `tsup.config.ts` with shebang injection,
ESM format, and conditional sourcemap/minify for production. ESLint configuration.

#### 3a. Application Version Configuration
The `package.json` `version` field MUST be set to the version value derived from the
version argument provided during skill invocation (e.g., `1.0.3`). If multiple versions
were provided, use the highest one.

Commander.js uses `package.json` version automatically for `--version` output. The CLI
entry point (`src/cli.ts`) must call `.version(packageJson.version)` on the Commander
program instance so that `<tool> --version` prints the correct version.

The version MUST also be included in JSON output when `--json` flag is used (e.g.,
`{"version": "1.0.3", "data": {...}}`).

#### 3b. `.env` File Generation from ENVIRONMENT.md
Generate a `.env` file at the project root by reading `ENVIRONMENT.md` from the project root.
The `.env` file maps ENVIRONMENT.md credential and platform values to the environment variable
names used by the CLI application. The spec must define the complete `.env` content with
actual values from ENVIRONMENT.md.

**Process:**
1. Read `ENVIRONMENT.md` from the project root
2. Extract credential values from `ENVIRONMENT.md` (`# Supporting 3rd Party Applications`
   and `# External Services` for API hosts, ports, tokens); read any toolchain paths
   (e.g., Node.js) from `DEVTOOL.md`
3. Map each value to the corresponding environment variable name used by the CLI
4. Generate the `.env` file with `KEY=value` pairs

**Example `.env` output (derived from ENVIRONMENT.md):**
```properties
# API
API_BASE_URL=http://localhost:8080/api/v1
API_KEY=

# Platform
NODE_HOME=C:\nvm4w\nodejs
```

**Rules:**
- Only include variables that are actually used by the application (via `process.env`)
- Use actual values from ENVIRONMENT.md — never use placeholders or `TODO`
- If ENVIRONMENT.md does not exist or a value is not found, use sensible defaults for local
  development (e.g., `localhost`, default ports)
- The `.env` file must be loaded using `dotenv` (add as a dependency if not already present)
- The `.env` file is gitignored

#### 4. Application Entry Point
`src/cli.ts` — the Commander.js `Program` setup: name, description, version, global options
(`--verbose`, `--json`, `--no-color`), command registration imports, and `program.parse()`.
See `references/command-patterns.md` for the root program setup, global option propagation
pattern, and async error handling with `parseAsync`.

#### 5. Project Directory Structure
Full `src/` directory tree with all files, named after actual commands and services
from the context.

#### 6. Shared Types
`src/types/index.ts` — all shared TypeScript interfaces and type aliases used across
commands and services.

#### 7. Terminal UI Utilities
- `src/ui/logger.ts` — chalk-based logger with `info`, `success`, `warn`, `error`,
  `debug` (gated on `--verbose`) methods
- `src/ui/spinner.ts` — ora wrapper with typed start/succeed/fail/stop helpers
- `src/ui/table.ts` — cli-table3 wrapper *(conditional on Table Output = yes)*
- `src/ui/output.ts` — Unified output handler respecting `--json` flag

#### 8. Error Handling
`src/errors.ts` — Base `CliError` class with exit code mapping. `handleError()` function
used in every command `action` handler to catch, format, and exit cleanly.

#### 9. User Configuration Management *(conditional — include only if User Config = yes)*
`src/config/user.config.ts` — `conf` setup with schema (Zod), typed accessors, and
migration strategy. Key names, default values, and OS storage paths.
See `references/config-patterns.md`.

#### 10. Project Configuration Management *(conditional — include only if Project Config = yes)*
`src/config/project.config.ts` — `cosmiconfig` loader with Zod validation. Config file
search path, supported formats, and merge strategy with defaults.
See `references/config-patterns.md`.

#### 11. HTTP Client Setup *(conditional — include only if HTTP Client = yes)*
`src/services/http.client.ts` — `got` instance with base URL, auth header injection,
retry configuration, and typed error handling.

#### 12. Shell Execution Utilities *(conditional — include only if Shell Execution = yes)*
`src/utils/shell.ts` — `execa` wrapper with logging, timeout, and error handling.

#### 13. Auto-Update Notifier *(conditional — include only if Auto-update = yes)*
`src/utils/updater.ts` — `update-notifier` integration called once at CLI startup with
non-blocking async check.

#### 14. Testing Strategy
Vitest configuration, command testing patterns with `process.argv` mocking, service unit
testing, config testing with temp directories.
See `references/testing-patterns.md`.

#### 15. Packaging & Distribution *(conditional — include only if Binary Packaging = yes)*
`tsup` build pipeline, `@yao-pkg/pkg` configuration, platform targets, npm scripts for
each platform binary, GitHub Actions release workflow stub.
See `references/packaging-patterns.md`.

**For npm-only distribution:** `package.json` `files`, `bin`, `engines`, `prepublishOnly`
script, `.npmignore`, semantic versioning guidance.

#### 16. Local Database *(conditional — include only if Local Database = yes)*
`src/db/schema.ts` — Drizzle table definitions (all entity tables derived from model files).
`src/db/client.ts` — `better-sqlite3` singleton with WAL mode, foreign keys, and
automatic migration runner on first open.
`src/db/path.ts` — `env-paths` based OS data directory resolution.
`src/db/repositories/` — One repository class per entity exposing typed CRUD and query
methods. `drizzle.config.ts`, `drizzle/` migration folder, and `db:generate` / `db:migrate`
/ `db:studio` npm scripts.
See `references/database-patterns.md`.

#### 17. Async Patterns *(conditional — include only if any async pattern is detected)*

Include only the sub-sections that apply. Multiple sub-sections may be included together.

**17a. Shared Signal Handling** *(include whenever any async pattern is yes)*
`src/utils/signal.ts` — `onSignal(cleanupFn)` utility that registers SIGINT and SIGTERM
handlers, runs the cleanup function, then exits with code 130 (Ctrl+C) or 0 (SIGTERM).
Used by polling loops, batch processors, and the daemon runner to ensure Ctrl+C always
produces a clean exit rather than a Node.js stack trace.

**17b. Polling** *(conditional — include only if Polling = yes)*
`src/utils/poll.ts` — `poll<T>(options)` function with configurable interval, timeout,
spinner integration, and `onTick` callback for dynamic status text. Command handlers
pass `--watch` / `--follow` / `--wait` flags down to the poll utility. Non-watch invocation
(fire-and-forget) must remain supported when the flag is absent.
See `references/async-patterns.md`.

**17c. Inline Batch Processing** *(conditional — include only if Inline Batch = yes)*
`src/utils/batch.ts` — `runBatch<TInput, TOutput>(options)` function with configurable
concurrency, bail-on-error mode, per-item error collection, and `onProgress` callback.
`src/ui/progress.ts` — `ProgressBar` wrapper over ora showing `[percent%] n/total — ETA Xs`.
When `Local Database = yes`, include the resume pattern: services filter out already-processed
IDs from the item list by querying the repository before the batch starts.
See `references/async-patterns.md`.

**17d. Background Daemon** *(conditional — include only if Background Daemon = yes)*
`src/daemon/runner.ts` — `runDaemon()` function implementing the daemon's event loop;
called when the process detects `MY_TOOL_DAEMON_MODE=1` in the environment before
Commander parses arguments.
`src/services/daemon.service.ts` — `DaemonManager` class with `start()` (spawn detached),
`stop()` (SIGTERM + timeout + SIGKILL), `isRunning()` (signal-0 check), `getStatus()`,
and `getRecentLogs()`. PID stored in `conf` (requires User Config = yes).
`src/commands/daemon/index.ts` — `start`, `stop`, `status`, `logs` sub-commands.
See `references/async-patterns.md`.

### What Goes in Each `<command-name>/SPEC.md` (Per-Command)

For EACH command from PRD.md, create a folder named after the command (kebab-case) and
generate a `SPEC.md` inside it. Each file is **self-contained** — a coding agent can
implement the command after the shared infrastructure is in place.

Each command SPEC.md must include:

- **Header** with command name and back-reference to root `SPECIFICATION.md`
- **Traceability**: user story IDs, NFR IDs, constraint IDs
- **Command definition**: full Commander.js `.command()` chain with all arguments,
  options, and description strings
- **Argument & Option contracts**: Zod schema for validation, complete option flag table
- **Prompt flow** *(conditional)*: `@inquirer/prompts` sequence for interactive mode
- **Service interface**: methods this command calls with TypeScript signatures
- **Service implementation**: full business logic, no terminal I/O
- **Output contract**: exact structure for `--json` output and human-readable output,
  including async output contracts if Polling or Inline Batch apply to this command
- **Error cases**: every error type, exit code, and user-facing message
- **Complete code samples** for every component

See `references/command-patterns.md` for the canonical command registration patterns
covering simple commands, sub-command groups, confirmation prompts, `--dry-run`,
tabular output, global option propagation, help text conventions, and exit code table.

## Changelog Append

After all specification files are successfully generated, append an entry to `CHANGELOG.md` in the application folder (`<app_folder>/CHANGELOG.md`):

1. Read `<app_folder>/CHANGELOG.md`. If it does not exist, create it with:
   ```markdown
   # Changelog

   - This file tracks all skill executions by version for this application.
   - The highest version recorded here is the current application version.
   - Skills MUST NOT execute for a version lower than the highest version in this file.

   ---
   ```
2. Search for a `## {version}` heading matching the current version.
3. If the section **exists**: append a new row to its table.
4. If the section **does not exist**: insert a new section after the `---` below the context header and before any existing `## vX.Y.Z` section (newest-first ordering), with a new table header and the first row.
5. Row format: `| {YYYY-MM-DD} | {application_name} | specgen-ts-cli | {module or "All"} | Generated TypeScript CLI technical specification |`
6. **Never modify or delete existing rows.**

## Output Format

```
<app_folder>/context/specification/
├── SPECIFICATION.md              ← Root: TOC + shared infrastructure
├── <command-1>/
│   └── SPEC.md                   ← Self-contained command blueprint
├── <command-2>/
│   └── SPEC.md
└── <command-N>/
    └── SPEC.md
```

**Sample code is mandatory.** Every component described in any spec file must include a
complete, self-explanatory code sample. The code must be continuous (no `// ...` gaps)
and usable as a direct reference by a coding agent.

## Constraints

These constraints are non-negotiable. Every code sample in the generated spec must follow
them.

### Universal Constraints

**Use ESM throughout.** The project sets `"type": "module"` in `package.json`. All
imports in TypeScript source use the `.js` extension (TypeScript resolves to `.ts`).
Never use `require()` or CommonJS `module.exports`.

**No `any` types.** Every function signature, variable, and generic must be explicitly
typed. Use `unknown` with runtime narrowing (Zod) instead of `any`.

**Constructor injection for services.** Services accept their dependencies (config, HTTP
client, logger) through the constructor. No global singletons imported directly in service
files. This enables clean unit testing with mocks.

**Commands must not contain business logic.** The command `action` handler is a thin
orchestrator: parse options → call service → format output → handle errors. All domain
logic lives in `src/services/`.

**Separate output from logic.** Service methods return typed data structures. The command
handler is responsible for formatting and printing. Services never call `console.log`
or manipulate terminal state.

**Always handle exit codes.** Every command `action` handler wraps its body in
`try/catch`. On error: print formatted message, call `process.exit(1)` (or the
appropriate code). On success: `process.exit(0)` is implicit.

**ESM import paths use `.js` extension.** In TypeScript source files:
```ts
import { UserConfig } from '../config/user.config.js'  // ✓ correct
import { UserConfig } from '../config/user.config'      // ✗ wrong
```

**All user-facing strings go through the logger or output module.** Never call
`console.log` directly in commands or services. Use `logger.info()`, `logger.error()`,
`output.print()`, etc.

**Zod for all external data.** Any data from config files, API responses, or CLI
arguments that crosses a system boundary must be parsed with a Zod schema before use.

**Use `@inquirer/prompts` not `inquirer`.** The modern scoped package is the officially
maintained version. Import individual prompt functions, not the legacy `inquirer` default.

### Conditional Constraints

**If Binary Packaging = yes:**
- Use dynamic `import()` for any modules not compatible with pkg's static analysis
- Avoid `__filename` / `__dirname` — use `import.meta.url` with `fileURLToPath`
- All asset files (templates, default configs) must be embedded via `pkg`'s `assets` config

**If User Config = yes:**
- Credentials and tokens must be stored using `conf` (uses OS keychain on macOS)
- Never write secrets to plain text files manually
- The `conf` schema must be defined with Zod and validated on read

**If Project Config = yes:**
- Config loading must be non-fatal if no config file is found (use defaults)
- Loaded config must be merged with defaults using a predictable precedence order:
  CLI flags > environment variables > project config file > user config > hardcoded defaults

**If HTTP Client = yes:**
- All API calls must use the shared `got` instance (never raw `fetch` or `axios`)
- HTTP errors must be caught, parsed for `statusCode`, and rethrown as `CliError`
- Authentication tokens must come from the config system, never hardcoded

**If Local Database = yes:**
- All database access must go through repository classes — services never use `db` directly
- Repositories receive `DbClient` via constructor injection — no global `getDb()` calls
  inside service files (only in the composition root `cli.ts` or service constructors)
- Every write statement (`insert`, `update`, `delete`) must call `.run()` to execute —
  Drizzle returns a prepared statement object that is not automatically executed
- All multi-step writes that must succeed or fail together must use `db.transaction()`
- JSON columns must be serialised with `JSON.stringify` on insert and `JSON.parse` on
  read — never store raw objects in `text` columns
- Migration files in `drizzle/` are committed to source control; never edit generated
  SQL files after commit — always generate new ones via `drizzle-kit generate`
- The database file path must come from `getDatabasePath()` — never hardcode a path

**If any Async Pattern is yes (Polling, Inline Batch, or Background Daemon):**
- Every long-running loop MUST register an `onSignal` handler before entering the loop
  and dispose it via the returned function when the loop exits normally
- Ctrl+C must NEVER produce a Node.js stack trace — the signal handler catches it,
  runs cleanup, and calls `process.exit(130)`
- SIGTERM must exit cleanly with code `0` — it signals intentional shutdown
  (e.g. `daemon stop`), not an error

**If Polling = yes:**
- Every command with a watch flag must also work without it (fire-and-forget behaviour
  is always supported; `--watch` / `--follow` is additive)
- The polling timeout must be configurable via a `--timeout <seconds>` option; the
  default (300s) is a maximum, not a guarantee

**If Inline Batch = yes:**
- Concurrency must be configurable via `--concurrency <n>` — never hardcode parallelism
- Both `--bail` (stop on first error) and the default (collect all errors, continue) must
  be supported
- Exit code must be `1` when any items fail, even if the majority succeeded
- The `onProgress` callback updates the spinner — service code never touches ora directly

**If Background Daemon = yes:**
- The daemon process is the SAME binary launched with `MY_TOOL_DAEMON_MODE=1` in the
  environment — never ship a separate daemon binary
- The daemon entry point check in `cli.ts` must appear BEFORE Commander parses `argv`,
  so the daemon mode is invisible to all user-facing `--help` output
- PID storage requires User Config (`conf`) — Background Daemon detection automatically
  forces User Config = yes in the determination summary
- `DaemonManager.isRunning()` must use signal-0 (`process.kill(pid, 0)`) to test
  process liveness — never rely on PID alone (PIDs are reused by the OS)

## Principles Embedded in the Spec

### Always-Applicable Principles
- ESM-first TypeScript with strict mode (`"strict": true`)
- Thin command action handlers — orchestrate, don't implement
- Services are pure TypeScript — no CLI concerns, fully testable
- Single output module respects `--json` flag for machine-readable output
- Every command has `--help` text that matches the user stories
- Errors produce clean, human-friendly messages with non-zero exit codes
- Verbose mode (`--verbose`, `-v`) reveals internal steps via `logger.debug()`
- All file paths use `node:path` and `node:url` — no raw string concatenation

### Conditional Principles
- **If Prompts = yes:** Interactive and non-interactive modes are both supported. Every
  prompt has a corresponding flag so the command can run non-interactively in CI.
- **If User Config = yes:** The `config` command exposes `get`, `set`, `list`, and
  `reset` sub-commands for user-visible settings.
- **If Local Database = yes:** SQLite is the single source of truth for all structured
  local data. `conf` remains for user preferences and tokens; SQLite is for anything
  with multiple rows, history, or relational structure. The database opens and migrates
  automatically on first command run — no manual `init-db` step required.
- **If Polling = yes:** Every watched command has a non-watch path that exits immediately.
  The `poll()` utility owns all timing and spinner state; the command handler only
  provides the `check` function and interprets the final result.
- **If Inline Batch = yes:** The `runBatch()` utility owns concurrency and error
  collection; the service owns per-item logic; the command handler owns progress display
  and final output. These three responsibilities must never be mixed.
- **If Background Daemon = yes:** The daemon runner (`runDaemon`) is a plain async
  function — it has no Commander, no prompts, and no user interaction. Its only
  interface is `MY_TOOL_DAEMON_MODE=1` (start) and SIGTERM (stop).
- **If Binary Packaging = yes:** The binary must work with zero Node.js dependency on the
  target machine. Asset embedding and path resolution must be validated for each platform.