TypeScript CLI Application Specification Generator

Optional Integration Versions

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

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:

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

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:

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

User Config Detection

Project Config Detection

Local Database Detection

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

HTTP Client Detection

Auto-Update Detection

Binary Packaging Detection

Async Pattern Detection

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

Polling Detection

Inline Batch Detection

Background Daemon Detection

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

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 SECRET.md

Generate a .env file at the project root by reading SECRET.md from the project root. The .env file maps SECRET.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 SECRET.md.

Process:

1. Read SECRET.md from the project root
2. Extract relevant values from # Credential section (API hosts, ports, tokens) and # Platform section (Node.js path, etc.)
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 SECRET.md):

# 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 SECRET.md — never use placeholders or TODO
• If SECRET.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:

   # 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