scaffold-cli

CLI のスキャフォールド

• 対象： references/ の固定テンプレートを使って、新しい TypeScript CLI または npm パッケージ（Node 24、TypeScript 7）を初期構築し、CI の初回成功から npm が OIDC 経由で公開できるパッケージにすることです。
• 対象外： Next.js の Web アプリ（scaffold-nextjs を使用）、既存のコードベースのフォルダー構成やモジュールの契約（codebase-architecture を使用）、既存 CLI の使いやすさの監査（dx-audit を使用）、既存パッケージのリリース（autoship を使用）です。

テンプレートには標準のツールチェーンが定義されています。プロジェクトの値に置き換え、インストール済みパッケージのバージョンに対してテンプレートの API を検証してください。互換性がないことが確認できた場合は、盲目的に再現するのではなく修正してください。このツールチェーンが標準です。tsup ではなく tsdown、jest ではなく vitest、eslint や prettier ではなく ultracite 経由の oxlint と oxfmt、chalk ではなく node:util の styleText、ora ではなく @clack/prompts を使用します。これらを入れ替えたり、レイアウトを再構成したりすると、テンプレートの注記が該当しないリポジトリになります。

参照ファイル

ファイル	読むタイミング
references/scaffold-configs.md	ステップ 3：package.json、tsconfig、tsdown、gitignore、ライセンス、changeset の設定、GitHub Actions
references/scaffold-source.md	ステップ 4～5：src/cli.ts、src/index.ts、src/types.ts、AGENTS.md、README.md、skills/SKILL.md
references/agent-friendly-cli.md	ステップ 4。コマンドが識別子、パス、URL を受け取る場合、または状態を変更する場合のみ：入力検証、ドライラン、確認、スキーマ
references/post-scaffold.md	ステップ 6～8：スキャフォールド後のコマンド、lefthook.yml の置き換え、検証チェックリスト、GitHub と npm の初期設定、トラブルシューティング

スキャフォールドのワークフロー

進捗を記録するため、このチェックリストをコピーしてください。

Scaffold progress:
- [ ] Step 1: Gather project info
- [ ] Step 2: Create directory structure
- [ ] Step 3: Generate config files
- [ ] Step 4: Generate source files
- [ ] Step 5: Generate docs and skill
- [ ] Step 6: Run post-scaffold commands
- [ ] Step 7: Validate scaffold
- [ ] Step 8: Bootstrap GitHub and npm (with the user's go-ahead)

ステップ 1：プロジェクト情報を集める

ユーザーが提供していない情報だけを尋ねてください。

変数	例	デフォルト	用途
{{name}}	md-tools	必須	package.json の名前、README のタイトル、npm パッケージ
{{description}}	CLI tool to convert content to markdown	必須	package.json、README、SKILL.md
{{bin}}	md	{{name}} と同じ	package.json の bin フィールド、CLI の使用例、skills フォルダー
{{repo}}	acme/md-tools	必須	package.json のリポジトリ、GitHub リポジトリ、npm の信頼済みパブリッシャー
{{author}}	Your Name	必須	package.json、LICENSE
{{year}}	2026	現在の年	LICENSE

{{repo}} は正確な GitHub の owner/name でなければなりません。npm provenance は、repository.url が公開元のリポジトリと異なる場合、公開を拒否します。

ステップ 2：ディレクトリー構成を作成する

{{name}}/
  .changeset/
  .github/
    workflows/
  src/
  skills/{{bin}}/

ステップ 3：設定ファイルを生成する

references/scaffold-configs.md を読み込みます。そこに記載されたすべてのファイルを生成し、各 {{placeholder}} を置き換えてください。

package.json、tsconfig.json、tsdown.config.ts、.gitignore、LICENSE.md、.changeset/config.json、.changeset/README.md、.github/workflows/ci.yml、.github/workflows/npm-publish.yml

ステップ 4：ソースファイルを生成する

references/scaffold-source.md を読み込み、次を生成します。

• src/cli.ts：エージェントに適したデフォルト設定を備えた Commander のエントリーポイント（--output text|json、--no-input、標準出力へのデータ出力／標準エラー出力へのログ出力の分離、JSON エラーエンベロープ）
• src/index.ts：公開 API のエクスポート
• src/types.ts：共有型定義

コマンドが識別子、パス、URL を受け取る場合、または状態を変更する場合は、references/agent-friendly-cli.md も読み込み、該当する固定パターンをコピーしてください。そのようなコマンドがない CLI の場合は省略します。

ステップ 5：ドキュメントとスキルを生成する

同じ references/scaffold-source.md を参照して、次を生成します。

• AGENTS.md：コマンド、アーキテクチャ、注意事項、エージェントの不変条件
• README.md：インストール、使用方法、API、エージェントスキルのインストール、ライセンス
• skills/{{bin}}/SKILL.md：エージェントスキルの定義

AGENTS.md を直接使用してください。CLAUDE.md のラッパーやシンボリックリンクは作成しないでください。

ステップ 6：スキャフォールド後のコマンドを実行する

references/post-scaffold.md を読み込みます。ultracite init と最初のコミットの間に lefthook.yml を上書きする手順も含め、指定された順序でコマンドを実行してください。

ステップ 7：スキャフォールドを検証する

references/post-scaffold.md の検証チェックリストを実行します。各項目は、出力が証拠となるコマンドです。チェックリストには、publint、arethetypeswrong、実際のファイルを使ったフックのテスト、プレースホルダーの一括確認が含まれています。

ステップ 8：GitHub と npm をセットアップする

ローカルのスキャフォールドの場合は、ステップ 7 で終了します。ユーザーがリモートのセットアップや公開をすでに依頼している場合は、許可された範囲で実施します。それ以外の場合は、作成または公開を尋ねる前に、準備したリポジトリとパッケージの識別情報を提示します。それ以外の場合は、references/post-scaffold.md の「GitHub と npm をセットアップする」に従います。リポジトリを作成してプッシュし、Actions による PR 作成を有効にして、パッケージが登録されるように手動で一度だけ 0.0.1 を公開してから、ワークフローを信頼されたパブリッシャーとして登録します。完了の証拠は、プッシュしたコミットで CI が成功することと、npm view {{name}} version の出力が 0.0.1 であることです。ここから先のリリースはすべて autoship に任せます。

依存関係

ランタイム： @clack/prompts、commander

開発用（package.json テンプレート内）： @changesets/cli、@types/node、tsdown、typescript、vitest

ultracite init が追加するもの。手動で記載しないでください： ultracite（init によって完全一致するバージョンに固定）、oxlint、oxfmt、lefthook、および check、fix、prepare スクリプト。手動で記載すると、スクリプトが重複し、init がインストールするものとバージョンが食い違います。

注意点

• tsdown はデフォルトで .mjs を出力します。 platform: node（デフォルト）では fixedExtension が有効なため、outputOptions.entryFileNames: "[name].js" のない設定でビルドすると、dist/cli.mjs、dist/index.mjs、dist/index.d.mts が生成され、bin と exports が存在しないファイルを参照します。テンプレートの outputOptions ブロックによって .js のまま出力されるため、不要なものとして削除しないでください。
• src/cli.ts にシバンを記述しないでください。 tsdown の banner が #!/usr/bin/env node を挿入するため、ソースにシバンを記述すると dist/cli.js で二重になります。2 つのビルドエントリーは分けたままにします。CLI エントリーには banner を設定して dts: false とし、ライブラリエントリーには dts: true を設定して banner は付けません。
• --passWithNoTests を付けない "test": "vitest run" は、テストファイルが 0 件のリポジトリで終了コード 1 を返します。 そのため、最初の CI 実行は失敗します。
• @changesets/cli@3 は changesets/action@v2 および publish-script: 入力と組み合わせて使用します。 @v1 では changesets v3 を操作できません。また、@v2 に v1 の publish: 入力を渡すと、パッケージのバージョンを更新した後、公開せずに成功扱いで終了します。テンプレートでは互換性のある組み合わせを使用しているため、どちらか一方だけをダウングレードしないでください。
• まだ存在しないパッケージは、npm の信頼されたパブリッシャーとして登録できません。 ステップ 8 で一度だけ手動の pnpm publish を実行してパッケージを作成し、ワークフローを登録するまでは、最初のリリース実行は E404 または ENEEDAUTH で失敗します。この公開は changeset が存在する前に行われるため、autoship のルールで許可されていない唯一の手動公開です。
• Node 22 に同梱される npm は 10.9.x です。OIDC による公開には npm 11.5.1 以降が必要です。 Node 24 には npm 11.19 が同梱されるため、両方のワークフローで node-version: 24 を固定しています。これを 22 に下げると、ENEEDAUTH によって公開に失敗します。プロジェクトでは pnpm を使用しますが、リリースワークフローで npm をアップグレードするのは、pnpm publish がアップロードを PATH 上の npm CLI に委ねることがあり、そこで古い npm が使われると OIDC による認証に失敗するためです。
• エージェント向けの出力は形式の契約です。 データは stdout に、ログと進捗状況は stderr に出力します。余計な console.log があると、--output json を解析するコンシューマーが動作しなくなります。stdin が TTY でないときは、決してプロンプトを表示しないでください。--no-input を尊重し、すべての値をフラグとして受け取るようにしないと、パイプ経由で実行した際にプロセスが停止します。

関連スキル

• autoship：初回の公開後の各リリースに対応します。変更セット、CI の監視、Version Packages PR、公開の検証、公開されなかったリリースの診断を行います。
• dx-audit：実際のコマンドが揃った段階で、CLI のフラグ、エラー、型を監査します。
• agents-md：コードベースの構造が整うにつれて、生成される AGENTS.md を拡充します。
• ghostwriter：実際の使用方法を説明できるようになった段階で、README を書き直します。

メンテナンス専用です：evals/evals.json にはこのスキルの変更に関する回帰シナリオが含まれています。ユーザーのタスク中には読み込まれません。