ai-check-template 0.2.0-alpha.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README-ja.md

@@ -0,0 +1,151 @@
+# ai-check-template（日本語版）
+
+**AI が生成したコードを、そのまま信じない。**
+
+`ai-check-template` は、AI が書いたコードを**検証・修正・安全にマージする**ためのテンプレート集です。
+
+> 「AI が実装しました」
+
+から、
+
+> 「AI が実装し、検査を通過し、リスクが可視化され、人間が証拠付きで受け入れた」
+
+への移行を支援します。
+
+> English version: [`README.md`](./README.md)
+
+---
+
+## What is this? / これは何?
+
+AI 駆動開発のためのテンプレート集。以下を提供:
+
+- AI 生成コード向けの**テスト設計思想**（Test Pyramid / Given-When-Then / QA 技法 / 形名参同）
+- 実装前に成功基準を AI に宣言させる **AI プロンプト雛形**
+- `ai:check` **実行スタック**（npm scripts / Claude Code hooks / シェルエントリポイント）
+- 同じ `ai:check` を PR で走らせる **GitHub Actions テンプレ**（direct workflow / reusable workflow example）
+- 主要スタック向け**プロファイル**（Next.js / vanilla React / Expo / Node CLI / Supabase + RLS）
+- 安全な初期導入のための alpha **CLI foundation**
+
+必要な部分をコピーして自プロジェクトに合わせ、検証可能なループを得る。特定の LLM・フレームワーク・ベンダーに依存しない設計。
+
+## Why? / なぜ?
+
+AI コーディングツール（Claude Code / Codex / Cursor 等）は実装を速くするが、**検証を速くはしない**。
+
+実務で AI 生成コードはよく以下に陥る:
+
+- 目視チェックは通るが、型 / lint / E2E で落ちる
+- 動いて見えるが、認可 / RLS / レート制限を無視している
+- 未使用 export / 不要コード / 意図しないスコープ拡散が残る
+- 「完了しました」と自己申告するが、実際は部分完了
+
+本リポは**形名参同**（事前宣言した成功基準と実測値の照合）を中核に据える。AI に自己採点させない。
+
+## Core loop / 中核ループ
+
+```
+要件
+   ↓
+受け入れ条件（Given-When-Then）
+   ↓
+テスト設計（QA 技法: 同値分割 / 境界値 / デシジョンテーブル / 状態遷移 / RLS 権限）
+   ↓
+AI 実装
+   ↓
+品質チェック（typecheck → lint → unit → diagnostics → E2E smoke）
+   ↓
+修正（AI が同一セッションで自動修正）
+   ↓
+再チェック
+   ↓
+人間の受け入れ判断（証拠付き）
+```
+
+各ステップに対応するテンプレ・プロンプトを配布します。
+
+## What you get / 提供物
+
+| レイヤ | 内容 |
+|---|---|
+| **思想ドキュメント** | [`formal-name-match.md`](./package-templates/docs/philosophy/formal-name-match.md)（形名参同）、[`test-pyramid.md`](./package-templates/docs/philosophy/test-pyramid.md)（責務分割）、[`given-when-then.md`](./package-templates/docs/philosophy/given-when-then.md)（GWT）、[`qa-techniques.md`](./package-templates/docs/philosophy/qa-techniques.md)（QA 技法） |
+| **テスト設計** | [`test-design-template.md`](./package-templates/docs/test-design-template.md) は要件を AC / Test Matrix / 検証コマンドへ落とすテンプレート |
+| **AI プロンプト雛形** | `decision-table` / `state-transition` / `boundary-value` / `rls-permission` / `plan-first` / [`diagnostic-repair.md`](./package-templates/prompts/diagnostic-repair.md) |
+| **実行スタック** | `scripts/ai-check.sh`、`scripts/ai-check-fast.sh`、`.claude/settings.hook-fragment.json`、`.claude/rules/test-rules.md`、`package.scripts.fragment.json` |
+| **CI テンプレ** | GitHub Actions `ai-check.yml`（フル）、`ai-check-fast.yml`（PR の fast ループ）、reusable workflow examples |
+| **Examples** | [`examples/nextjs-basic`](./examples/nextjs-basic/) は AI 生成コードの Before / After を示す runnable example |
+| **プロファイル** | `react-nextjs` / `react-vanilla` / `expo-rn` / `node-cli` / `supabase-rls` |
+| **CLI alpha** | [`docs/cli.md`](./docs/cli.md) は repository-local `init` command、read-only `doctor` command、guarded `update` command、install state（`.ai-check-template.json`）、profile-aware package script migrations、profile docs migration、support script defaults、`pnpm` / `npm` / `yarn` / `bun` の package manager detection と Claude hook / CI workflow command rendering、optional `--install-deps` npm dev dependency install、exact-managed workflow cleanup、advisory profile / missing-script diagnostics warnings、stale managed CI diagnostics、`doctor --strict`、`--profile`、`--package-manager`、`--ci`、`--claude-hooks`、`--dry-run`、`--overwrite`、`npm pack` readiness、`npm publish --dry-run --tag next` preflight を説明 |
+| **プロジェクト docs** | [`docs/vision.md`](./docs/vision.md)、[`docs/roadmap.md`](./docs/roadmap.md)、Phase 1 dogfooding プロトコル、[`初回 dogfooding report`](./docs/phase-1-initial-dogfooding-report.md) |
+
+## Quick start / 最短手順
+
+> v0.1.0 は「コピー＆カスタマイズ」型としてリリース済み。詳細は [`docs/releases/v0.1.0.md`](./docs/releases/v0.1.0.md)。repository-local の v0.2.0 alpha CLI、install state、profile-aware package script migrations、profile docs migration、support script defaults、package manager detection、package-manager-aware Claude hook / CI workflow rendering、optional `--install-deps`、exact-managed workflow cleanup、advisory profile / missing-script / stale managed CI diagnostics と `doctor --strict`、`npm pack` readiness、`npm publish --dry-run --tag next` preflight は [`docs/cli.md`](./docs/cli.md) を参照。actual npm / `npx ai-check-template init` 公開は今後の作業です。
+
+```bash
+# 1. リポをクローン
+git clone https://github.com/heidayo/ai-check-template.git
+
+# 2. alpha CLI init を dry-run するか、手動コピー用 profile を確認
+node ai-check-template/bin/ai-check-template.mjs init --target . --profile react-nextjs --dry-run
+node ai-check-template/bin/ai-check-template.mjs init --target . --profile react-nextjs --install-deps --dry-run
+node ai-check-template/bin/ai-check-template.mjs init --target . --profile node-cli --package-manager npm --dry-run
+node ai-check-template/bin/ai-check-template.mjs doctor --target . --ci none
+node ai-check-template/bin/ai-check-template.mjs doctor --target . --strict --json
+node ai-check-template/bin/ai-check-template.mjs update --target . --dry-run
+
+# 3. スタックに合う profile を確認
+cat ai-check-template/package-templates/profiles/react-nextjs/README.md
+
+# 4. 必要なファイルを自プロジェクトにコピー
+cp -r ai-check-template/package-templates/scripts ./scripts
+cp -r ai-check-template/package-templates/.claude ./.claude
+cp ai-check-template/package-templates/ci-examples/github-actions/ai-check.yml .github/workflows/
+cp ai-check-template/package-templates/ci-examples/github-actions/ai-check-fast.yml .github/workflows/
+# reusable workflow 方式にしたい場合は ai-quality-reusable.yml + ai-quality-call.yml をコピー
+
+# 5. scripts fragment を package.json にマージ
+cat ai-check-template/package-templates/package.scripts.fragment.json
+# 出力の "ai:check" / "ai:check:fast" を自プロジェクトの package.json の scripts に追加
+
+# 6. ループを回す
+pnpm ai:check
+```
+
+実行できる Before / After の例は [`examples/nextjs-basic`](./examples/nextjs-basic/) を参照。自分のタスクを実装前に整理する場合は [`test-design-template.md`](./package-templates/docs/test-design-template.md) から始め、`ai:check` や CI の diagnostic が失敗したら [`diagnostic-repair.md`](./package-templates/prompts/diagnostic-repair.md) を使います。
+
+詳細は [`docs/roadmap.md`](./docs/roadmap.md) と各 profile の README（[`package-templates/profiles/`](./package-templates/profiles/)）を参照。
+
+## Supported profiles / 対応プロファイル
+
+| Profile | 対象スタック | 注意点 |
+|---|---|---|
+| [`react-nextjs`](./package-templates/profiles/react-nextjs/) | Next.js App Router + TypeScript | フル toolchain（RD / Knip / Playwright / Semgrep） |
+| [`react-vanilla`](./package-templates/profiles/react-vanilla/) | 純 React + TypeScript（Vite / CRA） | Next.js 固有の React Doctor 診断は対象外 |
+| [`expo-rn`](./package-templates/profiles/expo-rn/) | Expo / React Native | React Doctor 非対応。E2E は Maestro / Detox |
+| [`node-cli`](./package-templates/profiles/node-cli/) | Node CLI / Library | UI / E2E なし、Static + Unit 中心 |
+| [`supabase-rls`](./package-templates/profiles/supabase-rls/) | Supabase + RLS（addon） | 他 profile と組み合わせ（例: `react-nextjs+supabase-rls`） |
+
+## Roadmap
+
+| バージョン | テーマ | 状態 |
+|---|---|---|
+| **v0.1.0** | 手動コピーで使うテンプレ集 | Released（[notes](./docs/releases/v0.1.0.md)） |
+| **v0.2.0** | CLI scaffolding（`npx ai-check-template init`） | 進行中（[alpha CLI docs + `npm pack` readiness](./docs/cli.md)） |
+| **v0.3.0+** | Reusable workflow + Composite Action（GitHub Marketplace） | 計画中 |
+
+詳細: [`docs/roadmap.md`](./docs/roadmap.md)。
+
+## Contributing / 貢献
+
+貢献を歓迎します。PR フロー / レーン選択は [`CONTRIBUTING.md`](./CONTRIBUTING.md)、コミュニティ規範は [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)、脆弱性報告は [`SECURITY.md`](./SECURITY.md) を参照。
+
+Issue / PR テンプレートは [`.github/`](./.github/) 配下。
+
+## License
+
+[Apache-2.0](./LICENSE)
+
+---
+
+> 本リポ自身も [SAGE Development System](https://github.com/heidayo/sage-ai-template)（Spec → Plan → Task → Execute → Verify）で開発しています。利用者は SAGE インストール不要（テンプレを使う側は SAGE 非依存）。SAGE 共存は opt-in。詳細は [`CONTRIBUTING.md`](./CONTRIBUTING.md) を参照。

package/README.md

@@ -0,0 +1,149 @@
+# ai-check-template
+
+**AI-generated code should not be trusted by default.**
+
+`ai-check-template` provides reusable templates for **verifying, repairing, and safely merging AI-generated code**. It helps teams move from:
+
+> "AI implemented it."
+
+to:
+
+> "AI implemented it, checks passed, risks are visible, and humans can accept it with evidence."
+
+> 日本語版 / Japanese: [`README-ja.md`](./README-ja.md)
+
+---
+
+## What is this?
+
+A template collection for AI-driven development. It bundles:
+
+- A **testing philosophy** built for AI-written code (Test Pyramid, Given-When-Then, QA techniques, Formal Name Match)
+- **AI prompt templates** that force the model to declare success criteria before implementing
+- An **`ai:check` execution stack** (npm scripts, Claude Code hooks, shell entry points)
+- **GitHub Actions templates** that run the same `ai:check` on every PR, including direct and reusable workflow examples
+- **Profiles** for common stacks (Next.js, vanilla React, Expo, Node CLI, Supabase + RLS)
+- An alpha **CLI foundation** for safer repository-local initialization
+
+You copy what you need, adapt to your project, and get a verifiable loop — without depending on any specific LLM, framework, or vendor.
+
+## Why?
+
+AI coding tools (Claude Code, Codex, Cursor) make implementation fast. They do not make verification fast.
+
+In practice, AI-generated code often:
+
+- Passes a quick eyeball check, then fails type / lint / E2E
+- Looks correct, but ignores authorization, RLS, or rate limiting
+- Leaves dead code, unused exports, or accidental scope drift
+- Self-reports "Done" when reality is "Partially done"
+
+`ai-check-template` is built around the principle of **Formal Name Match** (形名参同): declare the success criteria **before** implementation, then mechanically compare against the actual evidence after. AI cannot self-grade.
+
+## Core loop
+
+```
+Requirement
+   ↓
+Acceptance Criteria (Given-When-Then)
+   ↓
+Test Design (QA techniques: equivalence partitioning, boundary value, decision table, state transition, RLS permission)
+   ↓
+AI Implementation
+   ↓
+Quality Check (typecheck → lint → unit → diagnostics → E2E smoke)
+   ↓
+Repair (AI auto-fix in the same session)
+   ↓
+Re-check
+   ↓
+Human Acceptance (with evidence)
+```
+
+The repository ships templates and prompts for every step in this loop.
+
+## What you get
+
+| Layer | Contents |
+|---|---|
+| **Philosophy** | [`formal-name-match.md`](./package-templates/docs/philosophy/formal-name-match.md), [`test-pyramid.md`](./package-templates/docs/philosophy/test-pyramid.md), [`given-when-then.md`](./package-templates/docs/philosophy/given-when-then.md), [`qa-techniques.md`](./package-templates/docs/philosophy/qa-techniques.md) |
+| **Test design** | [`test-design-template.md`](./package-templates/docs/test-design-template.md) maps requirements to acceptance criteria, test matrix rows, and verification commands |
+| **Prompts** | `decision-table` / `state-transition` / `boundary-value` / `rls-permission` / `plan-first` / [`diagnostic-repair.md`](./package-templates/prompts/diagnostic-repair.md) |
+| **Execution stack** | `scripts/ai-check.sh`, `scripts/ai-check-fast.sh`, `.claude/settings.hook-fragment.json`, `.claude/rules/test-rules.md`, `package.scripts.fragment.json` |
+| **CI templates** | GitHub Actions `ai-check.yml` (full), `ai-check-fast.yml` (PR-only fast loop), and reusable workflow examples |
+| **Examples** | [`examples/nextjs-basic`](./examples/nextjs-basic/) shows a Before / After of AI-generated code under `ai-check-template` |
+| **Profiles** | `react-nextjs`, `react-vanilla`, `expo-rn`, `node-cli`, `supabase-rls` |
+| **CLI alpha** | [`docs/cli.md`](./docs/cli.md) documents the repository-local `init`, read-only `doctor`, and guarded `update` commands, install state (`.ai-check-template.json`), profile-aware package script migrations, profile docs migration, support script defaults, package manager detection plus Claude hook and CI workflow command rendering for `pnpm` / `npm` / `yarn` / `bun`, optional `--install-deps` npm dev dependency install, exact-managed workflow cleanup, advisory profile and missing-script diagnostics warnings, stale managed CI diagnostics, `doctor --strict`, `--profile`, `--package-manager`, `--ci`, `--claude-hooks`, `--dry-run`, `--overwrite`, `npm pack` readiness, and `npm publish --dry-run --tag next` preflight |
+| **Project docs** | [`docs/vision.md`](./docs/vision.md), [`docs/roadmap.md`](./docs/roadmap.md), Phase 1 dogfooding protocol, [`initial dogfooding report`](./docs/phase-1-initial-dogfooding-report.md) |
+
+## Quick start
+
+> v0.1.0 is released as "copy & adapt." See [`docs/releases/v0.1.0.md`](./docs/releases/v0.1.0.md). A repository-local v0.2.0 alpha CLI, install state, profile-aware package script migrations, profile docs migration, support script defaults, package manager detection, package-manager-aware Claude hook and CI workflow rendering, optional `--install-deps`, exact-managed workflow cleanup, advisory profile / missing-script / stale managed CI diagnostics with `doctor --strict`, `npm pack` readiness, and `npm publish --dry-run --tag next` preflight are available in [`docs/cli.md`](./docs/cli.md); actual npm / `npx ai-check-template init` publishing is still future work.
+
+```bash
+# 1. Clone or browse the templates
+git clone https://github.com/heidayo/ai-check-template.git
+
+# 2. Preview the alpha CLI init, or pick a profile and copy manually
+node ai-check-template/bin/ai-check-template.mjs init --target . --profile react-nextjs --dry-run
+node ai-check-template/bin/ai-check-template.mjs init --target . --profile react-nextjs --install-deps --dry-run
+node ai-check-template/bin/ai-check-template.mjs init --target . --profile node-cli --package-manager npm --dry-run
+node ai-check-template/bin/ai-check-template.mjs doctor --target . --ci none
+node ai-check-template/bin/ai-check-template.mjs doctor --target . --strict --json
+node ai-check-template/bin/ai-check-template.mjs update --target . --dry-run
+
+# 3. Pick a profile that matches your stack
+cat ai-check-template/package-templates/profiles/react-nextjs/README.md
+
+# 4. Copy what you need into your project
+cp -r ai-check-template/package-templates/scripts ./scripts
+cp -r ai-check-template/package-templates/.claude ./.claude
+cp ai-check-template/package-templates/ci-examples/github-actions/ai-check.yml .github/workflows/
+cp ai-check-template/package-templates/ci-examples/github-actions/ai-check-fast.yml .github/workflows/
+# Or copy ai-quality-reusable.yml + ai-quality-call.yml if you prefer reusable workflows.
+
+# 5. Merge the scripts fragment into your package.json
+cat ai-check-template/package-templates/package.scripts.fragment.json
+# Then add the "ai:check" and "ai:check:fast" entries to your package.json "scripts"
+
+# 6. Run the loop
+pnpm ai:check
+```
+
+To inspect a runnable Before / After example, see [`examples/nextjs-basic`](./examples/nextjs-basic/). To prepare your own task before implementation, start from [`test-design-template.md`](./package-templates/docs/test-design-template.md), then use [`diagnostic-repair.md`](./package-templates/prompts/diagnostic-repair.md) when `ai:check` or CI returns a failing diagnostic.
+
+Detailed walkthrough: see [`docs/roadmap.md`](./docs/roadmap.md) and the per-profile README under [`package-templates/profiles/`](./package-templates/profiles/).
+
+## Supported profiles
+
+| Profile | Target stack | Notes |
+|---|---|---|
+| [`react-nextjs`](./package-templates/profiles/react-nextjs/) | Next.js App Router + TypeScript | Full toolchain (RD / Knip / Playwright / Semgrep) |
+| [`react-vanilla`](./package-templates/profiles/react-vanilla/) | Plain React + TypeScript (Vite / CRA) | Next.js-specific RD checks skipped |
+| [`expo-rn`](./package-templates/profiles/expo-rn/) | Expo / React Native | React Doctor not supported; use Maestro / Detox for E2E |
+| [`node-cli`](./package-templates/profiles/node-cli/) | Node CLI / library | No UI / E2E; Static + Unit focus |
+| [`supabase-rls`](./package-templates/profiles/supabase-rls/) | Supabase + RLS (addon) | Combine with any of the above (e.g. `react-nextjs+supabase-rls`) |
+
+## Roadmap
+
+| Version | Theme | Status |
+|---|---|---|
+| **v0.1.0** | Manual templates for AI code verification | Released ([notes](./docs/releases/v0.1.0.md)) |
+| **v0.2.0** | CLI scaffolding (`npx ai-check-template init`) | In progress ([alpha CLI docs + `npm pack` readiness](./docs/cli.md)) |
+| **v0.3.0+** | Reusable workflow + Composite Action (GitHub Marketplace) | Planned |
+
+Full breakdown: [`docs/roadmap.md`](./docs/roadmap.md).
+
+## Contributing
+
+We welcome contributions. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the PR flow and lane selection, [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md) for community standards, and [`SECURITY.md`](./SECURITY.md) for vulnerability reporting.
+
+Issue and PR templates live under [`.github/`](./.github/).
+
+## License
+
+[Apache-2.0](./LICENSE)
+
+---
+
+> This repository is itself developed under the [SAGE Development System](https://github.com/heidayo/sage-ai-template) (Spec → Plan → Task → Execute → Verify). Contributors do not need SAGE installed to use the templates; SAGE coexistence is opt-in. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for details.

package/bin/ai-check-template.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../src/cli/index.mjs";
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(error.message);
+  process.exitCode = error.exitCode ?? 1;
+});