@clawplays/ospec-cli 0.3.1 → 0.3.3

package/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: ospec
+description: Document-driven OSpec workflow for AI-assisted development with change-ready initialization, execution, validation, and archive readiness.
+tags: [cli, workflow, automation, typescript, ospec, bootstrap]
+---
+
+# OSpec CLI
+
+Document-driven OSpec workflow for AI-assisted development with change-ready initialization, execution, validation, archiving, and docs maintenance.
+
+## Default Entry
+
+When the user says something short like:
+
+- `使用 ospec 初始化项目`
+- `使用 ospec 初始化这个目录`
+- `use ospec to initialize this directory`
+- `use ospec to initialize this repo`
+
+expand it internally as:
+
+1. initialize the repository with `ospec init` so it ends in a change-ready state
+2. if project context is missing and the AI can ask follow-up questions, ask one concise question for project summary or tech stack
+3. if the user declines or the flow is CLI-only, continue with placeholder project docs
+4. create the first change only when explicitly requested
+
+Do not force the user to repeat those steps manually when the request is already clear.
+
+Treat plain project-init intent as enough to trigger this flow. Do not require the user to restate the guardrails in a longer prompt.
+
+## Mandatory Init Execution
+
+When the user asks to initialize a directory, do not freehand the initialization flow.
+
+If the user intent is simply to initialize the project or current directory, treat that as a request for this mandatory flow.
+
+Use this exact behavior:
+
+1. run `ospec init [path]` when the directory is uninitialized or not yet change-ready
+2. if AI assistance is available and the repository lacks usable project context, ask one concise follow-up for summary or tech stack before init when helpful
+3. verify the actual filesystem result before claiming initialization is complete
+4. stop before `ospec new` unless the user explicitly asks to create a change
+
+Never replace `ospec init` with manual directory creation or a hand-written approximation.
+
+Do not say initialization is complete unless the managed protocol-shell assets and baseline project knowledge docs actually exist on disk.
+
+Required checks after `ospec init`:
+
+- `.skillrc`
+- `.ospec/`
+- `changes/active/`
+- `changes/archived/`
+- `SKILL.md`
+- `SKILL.index.json`
+- `build-index-auto.cjs`
+- `for-ai/ai-guide.md`
+- `for-ai/execution-protocol.md`
+- `for-ai/naming-conventions.md`
+- `for-ai/skill-conventions.md`
+- `for-ai/workflow-conventions.md`
+- `for-ai/development-guide.md`
+- `docs/project/overview.md`
+- `docs/project/tech-stack.md`
+- `docs/project/architecture.md`
+- `docs/project/module-map.md`
+- `docs/project/api-overview.md`
+
+During plain init, do not report `docs/SKILL.md`, `src/SKILL.md`, `tests/SKILL.md`, or business scaffold as if they were part of change-ready completion.
+
+## Prompt Profiles
+
+Use these prompt styles as the preferred mental model.
+
+### 1. Minimal Prompt
+
+Use when the user already trusts OSpec defaults.
+
+```text
+Use ospec to initialize this project.
+```
+
+### 2. Standard Prompt
+
+Use when you want short prompts and still want OSpec to finish initialization properly.
+
+```text
+Use ospec to initialize this project according to current OSpec rules.
+```
+
+### 3. Guided Init Prompt
+
+Use when you want the AI to gather missing context before initialization if needed.
+
+```text
+Use ospec to initialize this project. If project context is missing, ask me for a short summary or tech stack first. If I skip it, continue with placeholder docs.
+```
+
+### 4. Docs Maintenance Prompt
+
+Use when the repository is already initialized and the project knowledge layer needs a refresh or repair pass.
+
+```text
+Use ospec to refresh or repair the project knowledge layer for this directory. Do not create a change yet.
+```
+
+### 5. Change-Creation Prompt
+
+Use when the user is explicitly ready to move into execution.
+
+```text
+Use ospec to create and advance a change for this requirement. Respect the current project state and do not create queue work unless I ask for it.
+```
+
+### 6. Queue Prompt
+
+Use when the user explicitly wants multiple changes queued instead of one normal active change.
+
+```text
+Use ospec to break this TODO into multiple changes, create a queue, show the queue first, and do not run it yet.
+```
+
+### 7. Queue-Run Prompt
+
+Use when the user explicitly wants queue execution, not the normal single-change flow.
+
+```text
+Use ospec to create a change queue and execute it explicitly with ospec run manual-safe.
+```
+
+## Anti-Drift Rules
+
+Always keep these rules:
+
+- `ospec init` should leave the repository in a change-ready state
+- AI-assisted init may ask one concise follow-up question for missing summary or tech stack; if the user declines, continue with placeholder docs
+- `ospec docs generate` refreshes, repairs, or backfills project knowledge docs after initialization
+- when the user asks to initialize, execute the CLI init command and verify the protocol-shell files and `docs/project/*` files on disk before declaring success
+- do not assume the project is a web or Next.js project unless the repository or user makes that explicit
+- do not apply business scaffold during plain init or docs maintenance
+- do not generate `docs/project/bootstrap-summary.md`
+- do not create the first change automatically unless the user explicitly asks to create a change
+- do not enter queue mode unless the user explicitly asks for queue behavior
+- treat planning defaults as guidance, not as init-time templates
+- use the CLI commands for verification, archiving, and targeted inspection instead of ad-hoc filesystem edits
+
+## What The CLI Manages
+
+This CLI now covers:
+
+- change-ready initialization
+- project knowledge maintenance
+- layered skill files
+- execution-layer change workflow
+- planning defaults for proposal and task setup
+- explicit business scaffold generation when that scope is requested
+- Codex and Claude Code skill install and sync checks
+
+## Canonical Execution Files
+
+Treat these as the source of truth for active delivery work:
+
+- `.skillrc`
+- `docs/project/overview.md`
+- `docs/project/tech-stack.md`
+- `docs/project/architecture.md`
+- `changes/active/<change>/proposal.md`
+- `changes/active/<change>/tasks.md`
+- `changes/active/<change>/state.json`
+- `changes/active/<change>/verification.md`
+
+## Plugin Gates
+
+Before advancing an active change:
+
+- read `.skillrc.plugins` to detect enabled blocking plugins
+- if the current change activates `stitch_design_review`, inspect `changes/active/<change>/artifacts/stitch/approval.json`
+- when Stitch approval is missing or `status != approved`, treat the change as blocked and do not claim it is ready to continue or archive
+
+Do not fall back to the old `features/...` layout unless the target repository really still uses it.
+
+## Commands To Prefer
+
+```bash
+ospec status [path]
+ospec init [path]
+ospec init [path] --summary "..." --tech-stack node,react
+ospec docs generate [path]
+ospec new <change-name> [path]
+ospec docs status [path]
+ospec skills status [path]
+ospec changes status [path]
+ospec queue status [path]
+ospec queue add <change-name> [path]
+ospec queue next [path]
+ospec run start [path] --profile manual-safe
+ospec run status [path]
+ospec run step [path]
+ospec run resume [path]
+ospec run stop [path]
+ospec plugins status [path]
+ospec plugins approve stitch [changes/active/<change>]
+ospec plugins reject stitch [changes/active/<change>]
+ospec index check [path]
+ospec index build [path]
+ospec workflow show
+ospec workflow list-flags
+ospec progress [changes/active/<change>]
+ospec verify [changes/active/<change>]
+ospec archive [changes/active/<change>]
+ospec archive [changes/active/<change>] --check
+ospec finalize [changes/active/<change>]
+ospec skill status ospec
+ospec skill install ospec
+ospec skill status ospec-change
+ospec skill install ospec-change
+ospec skill status-claude ospec
+ospec skill install-claude ospec
+ospec skill status-claude ospec-change
+ospec skill install-claude ospec-change
+```
+
+Managed auto-sync targets for global install, `ospec init`, and `ospec update` are:
+
+- `ospec`
+- `ospec-change`
+
+Additional packaged skills remain available for explicit install, for example:
+
+```bash
+ospec skill install ospec-init
+ospec skill install-claude ospec-init
+```
+
+Preferred execution order for a new directory:
+
+```bash
+ospec init [path]
+ospec new <change-name> [path]
+ospec verify [changes/active/<change>]
+ospec finalize [changes/active/<change>]
+```
+
+Use `ospec docs generate [path]` later when you need a docs-only maintenance pass.
+
+Use `ospec status [path]` separately when you want an explicit troubleshooting snapshot.
+
+For completed changes, archive before commit. Use `ospec archive [changes/active/<change>]` to execute the archive and `--check` only when you want a readiness preview without moving files.
+
+For the normal closeout path, prefer `ospec finalize [changes/active/<change>]`. It should verify completeness, rebuild the index, archive the change, and leave Git commit as a separate manual step.
+
+## Project-Type Rules
+
+If the repository type is unclear:
+
+- inspect the real directory only when needed for troubleshooting or context gathering
+- let initialization stay stack-agnostic
+- allow the project to stay minimal except for OSpec-managed assets and baseline project docs
+- let later skills or explicit project-knowledge steps shape the actual stack
+
+This is important because valid OSpec projects include:
+
+- web applications
+- CLI tools
+- Unity projects
+- Godot projects
+- desktop apps
+- service backends
+- protocol-only repositories
+
+## Verification Discipline
+
+Before saying work is complete:
+
+1. verify the relevant active change
+2. confirm docs, skills, and index state if project knowledge changed
+3. keep `SKILL.index.json` current after meaningful skill updates
+4. treat `SKILL.index.json` section offsets as LF-normalized so Windows CRLF and Linux LF checkouts do not drift

package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OSpec"
+  short_description: "Inspect, initialize, and operate OSpec projects"
+  default_prompt: "Use $ospec to initialize this directory according to OSpec rules: use ospec init so the repository ends in change-ready state, reuse existing project docs when available, ask one concise follow-up for missing summary or tech stack in AI-assisted flows, fall back to placeholder docs when the user skips that context, do not assume a web template when the project type is unclear, do not create the first change automatically, and use ospec status or ospec changes status only when you need an explicit summary."

package/dist/cli.js

@@ -224,7 +224,7 @@ const services_1 = require("./services");
 
 
 
-const CLI_VERSION = '0.3.1';
+const CLI_VERSION = '0.3.3';
 
 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.3.1",
+  "version": "0.3.3",
   "description": "CLI tool for enforcing ospec workflow",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -47,8 +47,11 @@
   "files": [
     "dist/**",
     "assets/**",
+    "agents/openai.yaml",
     "scripts/postinstall.js",
     ".ospec/templates/hooks/**",
+    "SKILL.md",
+    "skill.yaml",
     "README.md",
     "README.zh-CN.md",
     "LICENSE"

package/skill.yaml

@@ -0,0 +1,151 @@
+name: ospec
+title: OSpec
+description: Document-driven OSpec workflow skill for AI-assisted development with Codex, Claude Code, and similar AI tools.
+version: 5.1.0
+author: OSpec Team
+license: MIT
+
+interface:
+  display_name: "OSpec"
+  short_description: "Inspect, initialize, and operate OSpec projects"
+  default_prompt: "Use $ospec to initialize this directory according to OSpec rules: use ospec init so the repository ends in change-ready state, reuse existing project docs when available, ask one concise follow-up for missing summary or tech stack in AI-assisted flows, fall back to placeholder docs when the user skips that context, do not assume a web template when the project type is unclear, and do not create the first change automatically."
+
+requires_local:
+  node: ">=18.0.0"
+  npm: ">=8.0.0"
+
+protocol:
+  project_files:
+    - ".skillrc"
+    - "SKILL.md"
+    - "SKILL.index.json"
+    - "build-index-auto.cjs"
+    - "for-ai/ai-guide.md"
+    - "for-ai/execution-protocol.md"
+    - "for-ai/naming-conventions.md"
+    - "for-ai/skill-conventions.md"
+    - "for-ai/workflow-conventions.md"
+    - "for-ai/development-guide.md"
+  feature_files:
+    - "changes/active/<feature>/proposal.md"
+    - "changes/active/<feature>/tasks.md"
+    - "changes/active/<feature>/state.json"
+    - "changes/active/<feature>/verification.md"
+  feature_name_format: "kebab-case"
+
+commands:
+  - id: status
+    command: "ospec status [project-dir]"
+    purpose: "Show project knowledge, execution status, and the recommended next step."
+  - id: init
+    command: "ospec init [root-dir]"
+    purpose: "Initialize the repository to a change-ready state from CLI."
+  - id: docs_generate
+    command: "ospec docs generate [project-dir]"
+    purpose: "Refresh, repair, or backfill the project knowledge layer for an already initialized repository."
+  - id: new
+    command: "ospec new <feature-name> [root-dir]"
+    purpose: "Create a new change under changes/active with proposal/tasks/state/verification/review."
+  - id: changes_status
+    command: "ospec changes status [project-dir]"
+    purpose: "Show PASS/WARN/FAIL protocol status for every active change."
+  - id: docs_status
+    command: "ospec docs status [project-dir]"
+    purpose: "Show project-doc coverage and missing knowledge docs."
+  - id: skills_status
+    command: "ospec skills status [project-dir]"
+    purpose: "Show layered SKILL coverage, module skills, and index status."
+  - id: index_check
+    command: "ospec index check [project-dir]"
+    purpose: "Show whether the skill index exists, is stale, or needs rebuild."
+  - id: index_build
+    command: "ospec index build [project-dir]"
+    purpose: "Rebuild the project skill index."
+  - id: progress
+    command: "ospec progress [changes/active/<feature>]"
+    purpose: "Show progress for a single active feature."
+  - id: verify
+    command: "ospec verify [changes/active/<feature>]"
+    purpose: "Check protocol completeness and optional-step coverage."
+  - id: archive
+    command: "ospec archive [changes/active/<feature>] [--check]"
+    purpose: "Archive a completed change after gate checks; use --check for readiness only."
+  - id: finalize
+    command: "ospec finalize [changes/active/<feature>]"
+    purpose: "Run verify + index refresh + archive as the standard closeout flow before commit."
+  - id: workflow_show
+    command: "ospec workflow show"
+    purpose: "Show workflow configuration for the current project."
+  - id: workflow_flags
+    command: "ospec workflow list-flags"
+    purpose: "List supported workflow feature flags."
+  - id: skill_status
+    command: "ospec skill status"
+    purpose: "Check whether a Codex-installed OSpec skill is present and in sync. Managed defaults are ospec and ospec-change."
+  - id: skill_install
+    command: "ospec skill install"
+    purpose: "Install or sync one OSpec skill package into ~/.codex/skills/. Managed defaults are ospec and ospec-change."
+  - id: skill_status_claude
+    command: "ospec skill status-claude"
+    purpose: "Check whether a Claude Code-installed OSpec skill is present and in sync. Managed defaults are ospec and ospec-change."
+  - id: skill_install_claude
+    command: "ospec skill install-claude"
+    purpose: "Install or sync one OSpec skill package into ~/.claude/skills/. Managed defaults are ospec and ospec-change."
+
+workflow:
+  read_order:
+    - ".skillrc"
+    - "changes/active/<feature>/proposal.md"
+    - "changes/active/<feature>/tasks.md"
+    - "changes/active/<feature>/state.json"
+    - "changes/active/<feature>/verification.md"
+  archive_requirements:
+    - "state.json.status must be ready_to_archive"
+    - "verification.md must be fully passed"
+    - "activated optional steps must appear in tasks.md and verification.md"
+    - "activated optional steps must be listed in verification.md.passed_optional_steps"
+  preferred_entry:
+    - "Run ospec init [path] when the directory is uninitialized or not yet change-ready."
+    - "Pass --summary, --tech-stack, or --architecture during init when CLI users already know the missing project context."
+    - "Run your project deployment and validation flow before archiving the active change."
+    - "Run ospec verify [changes/active/<change>] before archiving."
+    - "Use ospec status [path] when you want an explicit textual summary or troubleshooting snapshot."
+    - "Run ospec docs generate [path] later when you only need a docs maintenance pass."
+    - "Create the first change explicitly instead of assuming initialization will do it."
+
+guardrails:
+  - "Treat init as change-ready initialization, not protocol-shell-only initialization."
+  - "If the user intent is simply to initialize the project or current directory, still trigger the mandatory init flow without asking for a longer prompt."
+  - "When the user asks to initialize, use ospec init to take the repository to change-ready state and verify the managed protocol-shell files plus docs/project/* on disk before declaring success."
+  - "In AI-assisted flows, ask at most one concise follow-up for missing summary or tech stack before init when that context is unavailable."
+  - "If the user declines or no AI follow-up is possible, continue with placeholder docs instead of blocking init."
+  - "Do not assume the project is a web or Next.js project unless the repository or user makes that explicit."
+  - "Do not apply business scaffold during plain init."
+  - "Do not generate docs/project/bootstrap-summary.md during plain init or docs generate."
+  - "Do not create the first change automatically unless the user explicitly asks for a change."
+  - "Treat presets as planning defaults, not as init-time templates."
+
+prompt_profiles:
+  minimal: "Initialize this project with ospec. Use ospec init and verify the managed files before saying it is initialized."
+  standard: "Initialize this project with ospec according to current OSpec rules. Use ospec init so the repository ends in change-ready state, and do not create the first change automatically."
+  guided_init: "Use ospec to initialize this project. If the repository lacks project context, ask me for a short summary or tech stack first. If I skip it, continue with placeholder docs."
+  knowledge_backfill: "Use ospec to refresh or repair the project knowledge layer for this directory. Focus on docs, layered skills, and index state. Do not create a change yet."
+  change_creation: "Use ospec to create and advance a change for this requirement. Respect the current project state and do not treat init as auto-change creation."
+
+usage:
+  new_project_flow:
+    - "Initialize the repository with ospec init [path]."
+    - "If AI can ask follow-up questions and project context is missing, provide a short summary or tech stack once, or skip it and let placeholder docs be generated."
+    - "Create the first active change explicitly."
+    - "Run your project deployment and validation flow, then use ospec verify [changes/active/<change>]."
+    - "Archive the validated change with ospec finalize [changes/active/<change>]."
+    - "Verify .skillrc, changes/, .ospec/, build-index-auto.cjs, for-ai docs, and docs/project/* before claiming init is complete."
+    - "Use presets only as planning defaults; scaffold still requires explicit intent."
+  prompt_shortcuts:
+    - "initialize this project"
+    - "initialize this directory"
+    - "initialize the current project"
+    - "使用 ospec 初始化项目"
+    - "使用 ospec 初始化这个目录"
+    - "use ospec to initialize this directory"
+    - "use ospec to refresh or repair the project knowledge layer"