@clawplays/ospec-cli 0.2.0 → 0.3.0

package/README.ja.md

@@ -0,0 +1,290 @@
+<h1><a href="https://ospec.ai/" target="_blank" rel="noopener noreferrer">OSpec</a></h1>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@clawplays/ospec-cli"><img src="https://img.shields.io/npm/v/%40clawplays%2Fospec-cli?style=for-the-badge&logo=npm&label=npm" alt="npm"></a>
+  <a href="https://www.npmjs.com/package/@clawplays/ospec-cli"><img src="https://img.shields.io/npm/dm/%40clawplays%2Fospec-cli?style=for-the-badge&logo=npm&label=downloads&cacheSeconds=300" alt="npm downloads"></a>
+  <a href="https://github.com/clawplays/ospec/stargazers"><img src="https://img.shields.io/github/stars/clawplays/ospec?style=for-the-badge&logo=github" alt="GitHub stars"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/clawplays/ospec?style=for-the-badge&color=green" alt="License"></a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Node.js-18%2B-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 18+">
+  <img src="https://img.shields.io/badge/npm-8%2B-CB3837?style=flat-square&logo=npm&logoColor=white" alt="npm 8+">
+  <img src="https://img.shields.io/badge/language-TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript">
+  <img src="https://img.shields.io/badge/workflow-3_steps-0F766E?style=flat-square" alt="3-step workflow">
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> |
+  <a href="README.zh-CN.md">中文</a> |
+  <strong>日本語</strong>
+</p>
+
+OSpec は AI 対話コラボレーション向けのドキュメント駆動開発ワークフローです。最初にドキュメントで要件と変更を明確にし、その後 AI との協調で実装、検証、アーカイブを進めます。
+
+<p align="center">
+  <a href="docs/README.ja.md">ドキュメント</a> |
+  <a href="docs/prompt-guide.ja.md">プロンプトガイド</a> |
+  <a href="docs/usage.md">使い方</a> |
+  <a href="docs/project-overview.md">概要</a> |
+  <a href="docs/installation.md">インストール</a> |
+  <a href="https://github.com/clawplays/ospec/issues">Issues</a>
+</p>
+
+## npm でインストール
+
+```bash
+npm install -g @clawplays/ospec-cli
+```
+
+## 推奨プロンプト
+
+OSpec の利用は、ほとんどの場合この 3 ステップで十分です。
+
+1. プロジェクトディレクトリで OSpec を初期化する
+2. 要件、ドキュメント更新、バグ修正のための change を作成して進める
+3. 受け入れ完了後にその change をアーカイブする
+
+### 1. プロジェクトディレクトリで初期化する
+
+推奨プロンプト:
+
+```text
+OSpec を使ってこのプロジェクトを初期化してください。
+```
+
+Claude / Codex skill:
+
+```text
+$ospec を使ってこのプロジェクトを初期化してください。
+```
+
+<details>
+<summary>コマンドライン</summary>
+
+```bash
+ospec init .
+ospec init . --summary "Internal admin portal for operations"
+ospec init . --summary "Internal admin portal for operations" --tech-stack node,react,postgres
+ospec init . --architecture "Single web app with API and shared auth" --document-language ja-JP
+```
+
+メモ:
+
+- `--summary`: 生成ドキュメントに書き込むプロジェクト概要
+- `--tech-stack`: `node,react,postgres` のようなカンマ区切りの技術スタック
+- `--architecture`: 短いアーキテクチャ説明
+- `--document-language`: 生成ドキュメントの言語。通常は `en-US`、`zh-CN`、`ja-JP`
+- 値を渡した場合はその内容を使ってドキュメントを生成します
+- 値を渡さない場合は既存ドキュメントを優先利用し、無ければ補完用のプレースホルダを生成します
+
+</details>
+
+### 2. Change を作成して進める
+
+要件実装、ドキュメント更新、リファクタ、バグ修正はこの流れを使います。
+
+推奨プロンプト:
+
+```text
+OSpec を使ってこの要件の change を作成して進めてください。
+```
+
+Claude / Codex skill:
+
+```text
+$ospec-change を使ってこの要件の change を作成して進めてください。
+```
+
+![OSpec Change slash command example](docs/assets/ospecchange-slash-command.ja.svg)
+
+<details>
+<summary>コマンドライン</summary>
+
+```bash
+ospec new docs-homepage-refresh .
+ospec new fix-login-timeout .
+ospec new update-billing-copy .
+```
+
+</details>
+
+### 3. 受け入れ完了後にアーカイブする
+
+デプロイ、テスト、QA、またはその他の受け入れ確認が終わった後に、確認済みの change をアーカイブします。
+
+推奨プロンプト:
+
+```text
+OSpec を使って承認済みの change をアーカイブしてください。
+```
+
+Claude / Codex skill:
+
+```text
+$ospec を使って承認済みの change をアーカイブしてください。
+```
+
+<details>
+<summary>コマンドライン</summary>
+
+```bash
+ospec verify changes/active/<change-name>
+ospec finalize changes/active/<change-name>
+```
+
+メモ:
+
+- 先にプロジェクト固有のデプロイ、テスト、QA を実行します
+- `ospec verify` で change がアーカイブ可能か確認します
+- `ospec finalize` でインデックスを再構築し、change をアーカイブします
+
+</details>
+
+## OSpec の動作イメージ
+
+```text
+┌─────────────────────────────────────────────────────────────────┐
+│  1. USER REQUEST                                               │
+│     "Use OSpec to create and advance a change for this task."  │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  2. INIT TO CHANGE-READY                                       │
+│     ospec init                                                 │
+│     - .skillrc                                                 │
+│     - .ospec/                                                  │
+│     - changes/active + changes/archived                        │
+│     - root SKILL files and for-ai guidance                     │
+│     - docs/project/* baseline knowledge docs                   │
+│     - reuse docs or fall back to placeholders                  │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  3. EXECUTION                                                  │
+│     ospec new <change-name>                                    │
+│     ospec progress                                             │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  4. DEPLOY + VALIDATE                                          │
+│     project deploy / test / QA                                 │
+│     ospec verify                                               │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  5. ARCHIVE                                                    │
+│     ospec finalize                                             │
+│     rebuild index + archive                                    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 3 つの主要概念
+
+| 概念 | 説明 |
+|------|------|
+| **Protocol Shell** | `.skillrc`、`.ospec/`、`changes/`、ルートの `SKILL.md`、`SKILL.index.json`、`for-ai/` を含む最小の協調骨格 |
+| **Project Knowledge Layer** | `docs/project/*`、レイヤード skill ファイル、index 状態など AI が継続的に参照するコンテキスト |
+| **Active Change** | 1 つの要件専用の実行コンテナ。通常 `proposal.md`、`tasks.md`、`state.json`、`verification.md`、`review.md` を持つ |
+
+## 主な機能
+
+- **change-ready 初期化**: `ospec init` が protocol shell と基礎ドキュメントを一度に生成
+- **ガイド付き初期化**: AI 支援時は不足している概要や技術スタックを 1 回だけ確認可能
+- **ドキュメント保守**: `ospec docs generate` で後から知識レイヤを更新・修復
+- **change 実行の追跡**: proposal、tasks、state、verification、review を継続的に揃える
+- **キュー支援**: `queue` と `run` で複数 change の明示的な実行を管理
+- **プラグインゲート**: Stitch のデザインレビューと Checkpoint の自動化チェックをサポート
+- **標準クローズアウト**: `finalize` が検証、インデックス再構築、アーカイブを行う
+
+## プラグイン機能
+
+OSpec には、文書駆動ワークフローに UI レビューとフロー検証を追加する 2 つのオプションプラグインがあります。
+
+### Stitch
+
+Stitch はページデザインレビューとプレビュー共有に使います。ランディングページや UI 変更が多い change に向いています。
+
+AI 対話:
+
+```text
+OSpec を使って Stitch プラグインを有効にしてください。
+```
+
+Claude / Codex skill:
+
+```text
+$ospec を使って Stitch プラグインを有効にしてください。
+```
+
+<details>
+<summary>コマンドライン</summary>
+
+```bash
+ospec plugins enable stitch .
+```
+
+</details>
+
+### Checkpoint
+
+Checkpoint は画面フロー検証と自動チェックに使います。重要フローや受け入れ前のランタイム検証に向いています。
+
+AI 対話:
+
+```text
+OSpec を使って Checkpoint プラグインを有効にしてください。
+```
+
+Claude / Codex skill:
+
+```text
+$ospec を使って Checkpoint プラグインを有効にしてください。
+```
+
+<details>
+<summary>コマンドライン</summary>
+
+```bash
+ospec plugins enable checkpoint . --base-url http://127.0.0.1:3000
+```
+
+メモ:
+
+- `--base-url` は自動チェック対象となる起動中アプリの URL を指定します
+
+</details>
+
+## ドキュメント
+
+### コアドキュメント
+
+- [Docs Index](docs/README.ja.md)
+- [Prompt Guide](docs/prompt-guide.ja.md)
+- [Usage](docs/usage.md)
+- [Project Overview](docs/project-overview.md)
+- [Installation](docs/installation.md)
+- [Skills Installation](docs/skills-installation.md)
+
+### プラグイン仕様
+
+- [Stitch Plugin Spec](docs/stitch-plugin-spec.zh-CN.md)
+- [Checkpoint Plugin Spec](docs/checkpoint-plugin-spec.zh-CN.md)
+
+## リポジトリ構成
+
+```text
+dist/                       コンパイル済み CLI ランタイム
+assets/                     管理対象プロトコル資産、hooks、skill payload
+docs/                       公開ドキュメント
+scripts/                    リリースとインストール補助スクリプト
+.ospec/templates/hooks/     パッケージ同梱の Git hook テンプレート
+```
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/README.md

@@ -1,10 +1,8 @@
 <h1><a href="https://ospec.ai/" target="_blank" rel="noopener noreferrer">OSpec</a></h1>
 
-[简体中文](README.zh-CN.md)
-
 <p align="center">
   <a href="https://www.npmjs.com/package/@clawplays/ospec-cli"><img src="https://img.shields.io/npm/v/%40clawplays%2Fospec-cli?style=for-the-badge&logo=npm&label=npm" alt="npm"></a>
-  <a href="https://www.npmjs.com/package/@clawplays/ospec-cli"><img src="https://img.shields.io/npm/dm/%40clawplays%2Fospec-cli?style=for-the-badge&logo=npm&label=downloads" alt="npm downloads"></a>
+  <a href="https://www.npmjs.com/package/@clawplays/ospec-cli"><img src="https://img.shields.io/npm/dm/%40clawplays%2Fospec-cli?style=for-the-badge&logo=npm&label=downloads&cacheSeconds=300" alt="npm downloads"></a>
   <a href="https://github.com/clawplays/ospec/stargazers"><img src="https://img.shields.io/github/stars/clawplays/ospec?style=for-the-badge&logo=github" alt="GitHub stars"></a>
   <a href="LICENSE"><img src="https://img.shields.io/github/license/clawplays/ospec?style=for-the-badge&color=green" alt="License"></a>
 </p>
@@ -16,7 +14,13 @@
   <img src="https://img.shields.io/badge/workflow-3_steps-0F766E?style=flat-square" alt="3-step workflow">
 </p>
 
-OSpec is an AI-first CLI workflow system for initializing repositories to a change-ready state and delivering requirements through auditable change containers.
+<p align="center">
+  <strong>English</strong> |
+  <a href="README.zh-CN.md">中文</a> |
+  <a href="README.ja.md">日本語</a>
+</p>
+
+OSpec is a document-driven workflow for AI-assisted development, helping you define requirements and changes in docs first, then drive implementation, validation, and archive through AI collaboration.
 
 <p align="center">
   <a href="docs/README.md">Docs</a> |
@@ -37,11 +41,11 @@ npm install -g @clawplays/ospec-cli
 
 Most teams only need 3 steps to use OSpec:
 
-1. initialize the project
+1. initialize OSpec in your project directory
 2. create and advance one change for a requirement, document update, or bug fix
 3. archive the accepted change after deployment and validation are complete
 
-### 1. Initialize The Project
+### 1. Initialize OSpec In Your Project Directory
 
 Recommended prompt:
 
@@ -92,7 +96,7 @@ Claude / Codex skill mode:
 Use $ospec-change to create and advance a change for this requirement.
 ```
 
-![OSpec Change slash command example](docs/assets/ospecchange-slash-command.svg)
+![OSpec Change slash command example](docs/assets/ospecchange-slash-command.en.svg)
 
 <details>
 <summary>Command line</summary>
@@ -198,6 +202,64 @@ Archive notes:
 - **Skill management**: install and inspect OSpec skills for Codex and Claude Code.
 - **Standard closeout**: `finalize` verifies, rebuilds indexes, and archives the change before manual Git commit.
 
+## Plugin Features
+
+OSpec includes two optional plugins that extend the document-driven workflow with UI review and flow validation.
+
+### Stitch
+
+Use Stitch for page design review and preview collaboration, especially for landing pages, marketing pages, and UI-heavy changes.
+
+AI conversation:
+
+```text
+Use OSpec to enable the Stitch plugin.
+```
+
+Claude / Codex skill mode:
+
+```text
+Use $ospec to enable the Stitch plugin.
+```
+
+<details>
+<summary>Command line</summary>
+
+```bash
+ospec plugins enable stitch .
+```
+
+</details>
+
+### Checkpoint
+
+Use Checkpoint for app flow validation and automated checks, especially for submission flows, critical paths, and pre-acceptance runtime verification.
+
+AI conversation:
+
+```text
+Use OSpec to enable the Checkpoint plugin.
+```
+
+Claude / Codex skill mode:
+
+```text
+Use $ospec to enable the Checkpoint plugin.
+```
+
+<details>
+<summary>Command line</summary>
+
+```bash
+ospec plugins enable checkpoint . --base-url http://127.0.0.1:3000
+```
+
+Notes:
+
+- `--base-url` points to the running app used by automated checks
+
+</details>
+
 ## Documentation
 
 ### Core Docs
@@ -208,15 +270,11 @@ Archive notes:
 - [Project Overview](docs/project-overview.md)
 - [Installation](docs/installation.md)
 - [Skills Installation](docs/skills-installation.md)
-- [GitLab Custom Fork Sync](docs/custom-fork-sync.md)
-- [Upstream Brand Protection](docs/upstream-brand-protection.md)
 
-### Chinese-Only Advanced Specs
+### Plugin Specs
 
 - [Stitch Plugin Spec](docs/stitch-plugin-spec.zh-CN.md)
-- [Stitch Plugin Roadmap](docs/stitch-plugin-roadmap.zh-CN.md)
 - [Checkpoint Plugin Spec](docs/checkpoint-plugin-spec.zh-CN.md)
-- [Current Vibe Coding Spec Flow](docs/current-vibe-coding-spec-flow.zh-CN.md)
 
 ## Repository Structure
 

package/README.zh-CN.md

@@ -1,10 +1,8 @@
 <h1><a href="https://ospec.ai/" target="_blank" rel="noopener noreferrer">OSpec</a></h1>
 
-[English](README.md)
-
 <p align="center">
   <a href="https://www.npmjs.com/package/@clawplays/ospec-cli"><img src="https://img.shields.io/npm/v/%40clawplays%2Fospec-cli?style=for-the-badge&logo=npm&label=npm" alt="npm"></a>
-  <a href="https://www.npmjs.com/package/@clawplays/ospec-cli"><img src="https://img.shields.io/npm/dm/%40clawplays%2Fospec-cli?style=for-the-badge&logo=npm&label=downloads" alt="npm downloads"></a>
+  <a href="https://www.npmjs.com/package/@clawplays/ospec-cli"><img src="https://img.shields.io/npm/dm/%40clawplays%2Fospec-cli?style=for-the-badge&logo=npm&label=downloads&cacheSeconds=300" alt="npm downloads"></a>
   <a href="https://github.com/clawplays/ospec/stargazers"><img src="https://img.shields.io/github/stars/clawplays/ospec?style=for-the-badge&logo=github" alt="GitHub stars"></a>
   <a href="LICENSE"><img src="https://img.shields.io/github/license/clawplays/ospec?style=for-the-badge&color=green" alt="License"></a>
 </p>
@@ -16,7 +14,13 @@
   <img src="https://img.shields.io/badge/workflow-3_steps-0F766E?style=flat-square" alt="3-step workflow">
 </p>
 
-OSpec 是一个面向 AI 协作交付的 CLI 工作流系统，用来把仓库一次性初始化到可提 change 的状态，并通过可审计的 change 容器推进需求执行。
+<p align="center">
+  <a href="README.md">English</a> |
+  <strong>中文</strong> |
+  <a href="README.ja.md">日本語</a>
+</p>
+
+OSpec 是一个面向 AI 对话协作的文档驱动开发工作流，让你先用文档明确需求与变更，再驱动 AI 实现、验证与归档。
 
 <p align="center">
   <a href="docs/README.zh-CN.md">文档入口</a> |
@@ -37,11 +41,11 @@ npm install -g @clawplays/ospec-cli
 
 大多数团队使用 OSpec，只要 3 步：
 
-1. 初始化项目
+1. 在你的项目目录初始化项目
 2. 为文档更新、需求开发或 Bug 修复创建并推进一个 change
 3. 在需求验收通过后归档这个 change
 
-### 1. 初始化项目
+### 1. 在你的项目目录初始化项目
 
 推荐提示词：
 
@@ -92,7 +96,7 @@ Claude / Codex Skill 方式：
 使用 $ospec-change 为这个需求创建并推进一个 change。
 ```
 
-![OSpec Change Slash Command 示例](docs/assets/ospecchange-slash-command.svg)
+![OSpec Change Slash Command 示例](docs/assets/ospecchange-slash-command.zh-CN.svg)
 
 <details>
 <summary>命令行</summary>
@@ -198,6 +202,64 @@ ospec finalize changes/active/<change-name>
 - **skills 管理**：支持 Codex 和 Claude Code 的 OSpec skill 安装与检查。
 - **标准收口路径**：`finalize` 负责验证、重建索引和归档，Git 提交仍保持手动可控。
 
+## 插件功能
+
+OSpec 内置两个可选插件，用来把 UI 审核和流程验证接入到文档驱动交付流程中。
+
+### Stitch
+
+用于页面设计审核与预览协作，适合落地页、营销页和 UI 变化较多的需求。
+
+AI 对话方式：
+
+```text
+使用 OSpec 帮我打开 Stitch 插件。
+```
+
+Claude / Codex Skill 方式：
+
+```text
+使用 $ospec 帮我打开 Stitch 插件。
+```
+
+<details>
+<summary>命令行</summary>
+
+```bash
+ospec plugins enable stitch .
+```
+
+</details>
+
+### Checkpoint
+
+用于应用流程验证与自动化检查，适合提交流程、关键路径和验收前的运行验证。
+
+AI 对话方式：
+
+```text
+使用 OSpec 帮我打开 Checkpoint 插件。
+```
+
+Claude / Codex Skill 方式：
+
+```text
+使用 $ospec 帮我打开 Checkpoint 插件。
+```
+
+<details>
+<summary>命令行</summary>
+
+```bash
+ospec plugins enable checkpoint . --base-url http://127.0.0.1:3000
+```
+
+说明：
+
+- `--base-url` 用来指定运行中的应用地址，供自动化检查使用
+
+</details>
+
 ## 文档入口
 
 ### 核心文档
@@ -208,15 +270,11 @@ ospec finalize changes/active/<change-name>
 - [项目介绍](docs/project-overview.zh-CN.md)
 - [安装说明](docs/installation.zh-CN.md)
 - [Skills 安装说明](docs/skills-installation.zh-CN.md)
-- [GitLab 自定义 Fork 同步方案](docs/custom-fork-sync.zh-CN.md)
-- [上游品牌保护说明](docs/upstream-brand-protection.zh-CN.md)
 
-### 高级规范
+### 插件高级说明
 
 - [Stitch 插件规范](docs/stitch-plugin-spec.zh-CN.md)
-- [Stitch 插件路线图](docs/stitch-plugin-roadmap.zh-CN.md)
 - [Checkpoint 插件规范](docs/checkpoint-plugin-spec.zh-CN.md)
-- [当前 Vibe Coding Spec Flow](docs/current-vibe-coding-spec-flow.zh-CN.md)
 
 ## 仓库结构
 

package/dist/cli.js

@@ -224,7 +224,7 @@ const services_1 = require("./services");
 
 
 
-const CLI_VERSION = '0.2.0';
+const CLI_VERSION = '0.3.0';
 
 function showInitUsage() {
     console.log('Usage: ospec init [root-dir] [--summary "..."] [--tech-stack node,react] [--architecture "..."] [--document-language zh-CN|en-US]');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawplays/ospec-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "CLI tool for enforcing ospec workflow",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",