ospec

Category: Tools & Productivity | Uploader: clawplays | Downloads: 0 | Version: v1.0（Latest）

Protocol-shell-first OSpec workflow for initialization, project knowledge backfill, and change execution.

Changelog: Source: GitHub https://github.com/clawplays/ospec

Directory Structure

Current level: tree/main/

📁 .ospec/
- 📁 templates/
  - 📁 hooks/
    
    📄 post-merge 175 B
    
    📄 pre-commit 175 B
- 📄 asset-sources.json 13.8 KB
📁 agents/
- 📄 openai.yaml 621 B
📁 assets/
- 📁 for-ai/
  - 📁 en-US/
    
    📄 ai-guide.md 6.1 KB
    
    📄 execution-protocol.md 5.2 KB
  - 📁 zh-CN/
    
    📄 ai-guide.md 6.0 KB
    
    📄 execution-protocol.md 5.1 KB
- 📁 git-hooks/
  - 📄 post-merge 327 B
  - 📄 pre-commit 327 B
- 📁 global-skills/
  - 📁 claude/
    
    📁 ospec-change/
    
    📄 SKILL.md 6.7 KB
  - 📁 codex/
    
    📁 ospec-change/
    
    📁 agents/
    
    📄 openai.yaml 1.5 KB
    
    📄 SKILL.md 6.8 KB
    
    📄 skill.yaml 1.8 KB
- 📁 project-conventions/
  - 📁 en-US/
    
    📄 development-guide.md 891 B
    
    📄 naming-conventions.md 1.3 KB
    
    📄 skill-conventions.md 1.3 KB
    
    📄 workflow-conventions.md 4.4 KB
  - 📁 zh-CN/
    
    📄 development-guide.md 758 B
    
    📄 naming-conventions.md 1.3 KB
    
    📄 skill-conventions.md 1.2 KB
    
    📄 workflow-conventions.md 4.2 KB
📁 dist/
- 📁 adapters/
  - 📄 codex-stitch-adapter.js 16.7 KB
  - 📄 gemini-stitch-adapter.js 16.2 KB
  - 📄 playwright-checkpoint-adapter.js 99.3 KB
- 📁 advanced/
  - 📄 BatchOperations.d.ts 1.2 KB
  - 📄 BatchOperations.d.ts.map 1.3 KB
  - 📄 BatchOperations.js 5.9 KB
  - 📄 BatchOperations.js.map 4.2 KB
  - 📄 CachingLayer.d.ts 1.2 KB
  - 📄 CachingLayer.d.ts.map 1.1 KB
  - 📄 CachingLayer.js 3.4 KB
  - 📄 CachingLayer.js.map 3.3 KB
  - 📄 FeatureUpdater.d.ts 1.2 KB
  - 📄 FeatureUpdater.d.ts.map 1.0 KB
  - 📄 FeatureUpdater.js 5.5 KB
  - 📄 FeatureUpdater.js.map 3.5 KB
  - 📄 index.d.ts 760 B
  - 📄 index.d.ts.map 659 B
  - 📄 index.js 2.0 KB
  - 📄 index.js.map 414 B
  - 📄 PerformanceMonitor.d.ts 1.2 KB
  - 📄 PerformanceMonitor.d.ts.map 1.1 KB
  - 📄 PerformanceMonitor.js 3.8 KB
  - 📄 PerformanceMonitor.js.map 3.6 KB
  - 📄 StatePersistence.d.ts 1.4 KB
  - 📄 StatePersistence.d.ts.map 1.1 KB
  - 📄 StatePersistence.js 5.1 KB
  - 📄 StatePersistence.js.map 3.4 KB
- 📁 cli/
  - 📁 commands/
    
    📄 config.d.ts 91 B
    
    📄 config.d.ts.map 136 B
    
    📄 config.js 103 B
    
    📄 config.js.map 135 B
    
    📄 feature.d.ts 103 B
    
    📄 feature.d.ts.map 138 B
    
    📄 feature.js 115 B
    
    📄 feature.js.map 137 B
    
    📄 index.d.ts 97 B
    
    📄 index.d.ts.map 134 B
    
    📄 index.js 109 B
    
    📄 index.js.map 133 B
    
    📄 project.d.ts 103 B
    
    📄 project.d.ts.map 138 B
    
    📄 project.js 115 B
    
    📄 project.js.map 137 B
    
    📄 validate.d.ts 97 B
    
    📄 validate.d.ts.map 140 B
    
    📄 validate.js 109 B
    
    📄 validate.js.map 139 B
  - 📄 index.d.ts 91 B
  - 📄 index.d.ts.map 122 B
  - 📄 index.js 103 B
  - 📄 index.js.map 121 B
- 📁 commands/
  - 📄 ArchiveCommand.d.ts 517 B
  - 📄 ArchiveCommand.d.ts.map 495 B
  - 📄 ArchiveCommand.js 12.8 KB
  - 📄 ArchiveCommand.js.map 6.5 KB
  - 📄 BaseCommand.d.ts 744 B
  - 📄 BaseCommand.d.ts.map 663 B
  - 📄 BaseCommand.js 1004 B
  - 📄 BaseCommand.js.map 773 B
  - 📄 BatchCommand.d.ts 211 B
  - 📄 BatchCommand.d.ts.map 284 B
  - 📄 BatchCommand.js 1.7 KB
  - 📄 BatchCommand.js.map 1.3 KB
  - 📄 ChangesCommand.d.ts 107 B
  - 📄 ChangesCommand.js 3.4 KB
  - 📄 DocsCommand.d.ts 210 B
  - 📄 DocsCommand.d.ts.map 277 B
  - 📄 DocsCommand.js 6.2 KB
  - 📄 DocsCommand.js.map 3.7 KB
  - 📄 FinalizeCommand.d.ts 91 B
  - 📄 FinalizeCommand.js 979 B
  - 📄 index.d.ts 947 B
  - 📄 index.d.ts.map 764 B
  - 📄 index.js 3.7 KB
  - 📄 index.js.map 653 B
  - 📄 IndexCommand.d.ts 212 B
  - 📄 IndexCommand.d.ts.map 279 B
  - 📄 IndexCommand.js 2.6 KB
  - 📄 IndexCommand.js.map 2.2 KB
  - 📄 InitCommand.d.ts 189 B
  - 📄 InitCommand.d.ts.map 262 B
  - 📄 InitCommand.js 2.8 KB
  - 📄 InitCommand.js.map 1.2 KB
  - 📄 NewCommand.d.ts 385 B
  - 📄 NewCommand.d.ts.map 280 B
  - 📄 NewCommand.js 12.1 KB
  - 📄 NewCommand.js.map 2.3 KB
  - 📄 PluginsCommand.d.ts 2.1 KB
  - 📄 PluginsCommand.js 129.3 KB
  - 📄 ProgressCommand.d.ts 201 B
  - 📄 ProgressCommand.d.ts.map 271 B
  - 📄 ProgressCommand.js 4.3 KB
  - 📄 ProgressCommand.js.map 2.7 KB
  - 📄 QueueCommand.d.ts 325 B
  - 📄 QueueCommand.js 5.8 KB
  - 📄 RunCommand.d.ts 372 B
  - 📄 RunCommand.js 7.5 KB
  - 📄 SkillCommand.d.ts 1.1 KB
  - 📄 SkillCommand.d.ts.map 695 B
  - 📄 SkillCommand.js 25.8 KB
  - 📄 SkillCommand.js.map 12.7 KB
  - 📄 SkillsCommand.d.ts 214 B
  - 📄 SkillsCommand.d.ts.map 281 B
  - 📄 SkillsCommand.js 3.3 KB
  - 📄 SkillsCommand.js.map 2.7 KB
  - 📄 StatusCommand.d.ts 234 B
  - 📄 StatusCommand.d.ts.map 290 B
  - 📄 StatusCommand.js 7.4 KB
  - 📄 StatusCommand.js.map 4.6 KB
  - 📄 UpdateCommand.d.ts 295 B
  - 📄 UpdateCommand.js 12.9 KB
  - 📄 VerifyCommand.d.ts 197 B
  - 📄 VerifyCommand.d.ts.map 266 B
  - 📄 VerifyCommand.js 14.5 KB
  - 📄 VerifyCommand.js.map 5.7 KB
  - 📄 WorkflowCommand.d.ts 355 B
  - 📄 WorkflowCommand.d.ts.map 328 B
  - 📄 WorkflowCommand.js 6.1 KB
  - 📄 WorkflowCommand.js.map 3.2 KB
- 📁 core/
  - 📄 constants.d.ts 1.2 KB
  - 📄 constants.d.ts.map 438 B
  - 📄 constants.js 2.0 KB
  - 📄 constants.js.map 1.4 KB
  - 📄 errors.d.ts 1.2 KB
  - 📄 errors.d.ts.map 916 B
  - 📄 errors.js 2.6 KB
  - 📄 errors.js.map 1.6 KB
  - 📄 index.d.ts 139 B
  - 📄 index.d.ts.map 184 B
  - 📄 index.js 948 B
  - 📄 index.js.map 174 B
  - 📄 types.d.ts 9.6 KB
  - 📄 types.d.ts.map 5.8 KB
  - 📄 types.js 110 B
  - 📄 types.js.map 110 B
- 📁 presets/
  - 📄 ProjectPresets.d.ts 1.8 KB
  - 📄 ProjectPresets.d.ts.map 1.5 KB
  - 📄 ProjectPresets.js 10.6 KB
  - 📄 ProjectPresets.js.map 5.7 KB
- 📁 scaffolds/
  - 📄 ProjectScaffoldPresets.d.ts 1.1 KB
  - 📄 ProjectScaffoldPresets.d.ts.map 893 B
  - 📄 ProjectScaffoldPresets.js 9.2 KB
  - 📄 ProjectScaffoldPresets.js.map 5.1 KB
- 📁 services/
  - 📁 templates/
    
    📄 ExecutionTemplateBuilder.d.ts 691 B
    
    📄 ExecutionTemplateBuilder.d.ts.map 615 B
    
    📄 ExecutionTemplateBuilder.js 8.9 KB
    
    📄 ExecutionTemplateBuilder.js.map 5.7 KB
    
    📄 ProjectTemplateBuilder.d.ts 2.8 KB
    
    📄 ProjectTemplateBuilder.d.ts.map 2.2 KB
    
    📄 ProjectTemplateBuilder.js 61.2 KB
    
    📄 ProjectTemplateBuilder.js.map 20.5 KB
    
    📄 TemplateBuilderBase.d.ts 1.1 KB
    
    📄 TemplateBuilderBase.d.ts.map 1.0 KB
    
    📄 TemplateBuilderBase.js 2.2 KB
    
    📄 TemplateBuilderBase.js.map 2.7 KB
    
    📄 TemplateInputFactory.d.ts 948 B
    
    📄 TemplateInputFactory.d.ts.map 763 B
    
    📄 TemplateInputFactory.js 14.7 KB
    
    📄 TemplateInputFactory.js.map 11.8 KB
    
    📄 templateTypes.d.ts 2.9 KB
    
    📄 templateTypes.d.ts.map 2.8 KB
    
    📄 templateTypes.js 118 B
    
    📄 templateTypes.js.map 143 B
  - 📄 ConfigManager.d.ts 673 B
  - 📄 ConfigManager.d.ts.map 668 B
  - 📄 ConfigManager.js 20.8 KB
  - 📄 ConfigManager.js.map 2.6 KB
  - 📄 FeatureManager.d.ts 119 B
  - 📄 FeatureManager.d.ts.map 145 B
  - 📄 FeatureManager.js 131 B
  - 📄 FeatureManager.js.map 144 B
  - 📄 FileService.d.ts 865 B
  - 📄 FileService.d.ts.map 1.1 KB
  - 📄 FileService.js 5.0 KB
  - 📄 FileService.js.map 3.5 KB
  - 📄 index.d.ts 2.6 KB
  - 📄 index.d.ts.map 1.9 KB
  - 📄 index.js 8.2 KB
  - 📄 index.js.map 2.0 KB
  - 📄 IndexBuilder.d.ts 508 B
  - 📄 IndexBuilder.d.ts.map 521 B
  - 📄 IndexBuilder.js 5.4 KB
  - 📄 IndexBuilder.js.map 4.8 KB
  - 📄 Logger.d.ts 503 B
  - 📄 Logger.d.ts.map 616 B
  - 📄 Logger.js 1.3 KB
  - 📄 Logger.js.map 1.4 KB
  - 📄 ProjectAssetRegistry.d.ts 562 B
  - 📄 ProjectAssetRegistry.d.ts.map 563 B
  - 📄 ProjectAssetRegistry.js 3.8 KB
  - 📄 ProjectAssetRegistry.js.map 1.8 KB
  - 📄 ProjectAssetService.d.ts 1.7 KB
  - 📄 ProjectAssetService.d.ts.map 1.3 KB
  - 📄 ProjectAssetService.js 10.2 KB
  - 📄 ProjectAssetService.js.map 7.1 KB
  - 📄 ProjectScaffoldCommandService.d.ts 2.5 KB
  - 📄 ProjectScaffoldCommandService.d.ts.map 2.2 KB
  - 📄 ProjectScaffoldCommandService.js 6.8 KB
  - 📄 ProjectScaffoldCommandService.js.map 4.6 KB
  - 📄 ProjectScaffoldService.d.ts 1.7 KB
  - 📄 ProjectScaffoldService.d.ts.map 1.5 KB
  - 📄 ProjectScaffoldService.js 18.9 KB
  - 📄 ProjectScaffoldService.js.map 10.5 KB
  - 📄 ProjectService.d.ts 9.1 KB
  - 📄 ProjectService.d.ts.map 6.6 KB
  - 📄 ProjectService.js 94.5 KB
  - 📄 ProjectService.js.map 62.3 KB
  - 📄 QueueService.d.ts 952 B
  - 📄 QueueService.js 6.6 KB
  - 📄 RunService.d.ts 1.6 KB
  - 📄 RunService.js 19.1 KB
  - 📄 SkillParser.d.ts 813 B
  - 📄 SkillParser.d.ts.map 636 B
  - 📄 SkillParser.js 3.0 KB
  - 📄 SkillParser.js.map 2.6 KB
  - 📄 StateManager.d.ts 827 B
  - 📄 StateManager.d.ts.map 715 B
  - 📄 StateManager.js 4.6 KB
  - 📄 StateManager.js.map 1.9 KB
  - 📄 TemplateEngine.d.ts 3.7 KB
  - 📄 TemplateEngine.d.ts.map 2.9 KB
  - 📄 TemplateEngine.js 5.5 KB
  - 📄 TemplateEngine.js.map 4.3 KB
  - 📄 TemplateGenerator.d.ts 1.4 KB
  - 📄 TemplateGenerator.d.ts.map 1.0 KB
  - 📄 TemplateGenerator.js 9.4 KB
  - 📄 TemplateGenerator.js.map 4.6 KB
  - 📄 ValidationService.d.ts 477 B
  - 📄 ValidationService.d.ts.map 418 B
  - 📄 ValidationService.js 1.2 KB
  - 📄 ValidationService.js.map 975 B
  - 📄 Validator.d.ts 91 B
  - 📄 Validator.d.ts.map 135 B
  - 📄 Validator.js 103 B
  - 📄 Validator.js.map 134 B
- 📁 tools/
  - 📄 build-index.js 18.0 KB
- 📁 utils/
  - 📄 DateUtils.d.ts 372 B
  - 📄 DateUtils.d.ts.map 341 B
  - 📄 DateUtils.js 1.1 KB
  - 📄 DateUtils.js.map 1.2 KB
  - 📄 helpers.d.ts 89 B
  - 📄 helpers.d.ts.map 128 B
  - 📄 helpers.js 101 B
  - 📄 helpers.js.map 127 B
  - 📄 index.d.ts 154 B
  - 📄 index.d.ts.map 185 B
  - 📄 index.js 963 B
  - 📄 index.js.map 175 B
  - 📄 logger.d.ts 88 B
  - 📄 logger.d.ts.map 126 B
  - 📄 logger.js 100 B
  - 📄 logger.js.map 125 B
  - 📄 path.d.ts 92 B
  - 📄 path.d.ts.map 122 B
  - 📄 path.js 104 B
  - 📄 path.js.map 121 B
  - 📄 PathUtils.d.ts 500 B
  - 📄 PathUtils.d.ts.map 489 B
  - 📄 PathUtils.js 2.5 KB
  - 📄 PathUtils.js.map 1002 B
  - 📄 StringUtils.d.ts 566 B
  - 📄 StringUtils.d.ts.map 507 B
  - 📄 StringUtils.js 1.1 KB
  - 📄 StringUtils.js.map 1.1 KB
  - 📄 subcommandHelp.d.ts 580 B
  - 📄 subcommandHelp.d.ts.map 431 B
  - 📄 subcommandHelp.js 5.7 KB
  - 📄 subcommandHelp.js.map 764 B
- 📁 workflow/
  - 📄 ArchiveGate.d.ts 966 B
  - 📄 ArchiveGate.d.ts.map 910 B
  - 📄 ArchiveGate.js 4.3 KB
  - 📄 ArchiveGate.js.map 3.1 KB
  - 📄 ConfigurableWorkflow.d.ts 2.4 KB
  - 📄 ConfigurableWorkflow.d.ts.map 1.6 KB
  - 📄 ConfigurableWorkflow.js 6.6 KB
  - 📄 ConfigurableWorkflow.js.map 5.0 KB
  - 📄 HookSystem.d.ts 1.0 KB
  - 📄 HookSystem.d.ts.map 997 B
  - 📄 HookSystem.js 1.8 KB
  - 📄 HookSystem.js.map 1.9 KB
  - 📄 index.d.ts 1.2 KB
  - 📄 index.d.ts.map 832 B
  - 📄 index.js 3.4 KB
  - 📄 index.js.map 534 B
  - 📄 IndexRegenerator.d.ts 1.1 KB
  - 📄 IndexRegenerator.d.ts.map 978 B
  - 📄 IndexRegenerator.js 5.4 KB
  - 📄 IndexRegenerator.js.map 3.4 KB
  - 📄 PluginWorkflowComposer.d.ts 3.6 KB
  - 📄 PluginWorkflowComposer.js 8.3 KB
  - 📄 SkillUpdateEngine.d.ts 947 B
  - 📄 SkillUpdateEngine.d.ts.map 1.0 KB
  - 📄 SkillUpdateEngine.js 4.1 KB
  - 📄 SkillUpdateEngine.js.map 2.4 KB
  - 📄 VerificationSystem.d.ts 865 B
  - 📄 VerificationSystem.d.ts.map 850 B
  - 📄 VerificationSystem.js 4.1 KB
  - 📄 VerificationSystem.js.map 3.1 KB
  - 📄 WorkflowEngine.d.ts 709 B
  - 📄 WorkflowEngine.d.ts.map 665 B
  - 📄 WorkflowEngine.js 2.3 KB
  - 📄 WorkflowEngine.js.map 2.0 KB
- 📄 .npmignore 9 B
- 📄 cli.d.ts 64 B
- 📄 cli.d.ts.map 100 B
- 📄 cli.js 12.7 KB
- 📄 cli.js.map 4.7 KB
- 📄 index.d.ts 265 B
- 📄 index.d.ts.map 260 B
- 📄 index.js 1.1 KB
- 📄 index.js.map 218 B
📁 docs/
- 📄 checkpoint-plugin-spec.zh-CN.md 20.2 KB
- 📄 current-vibe-coding-spec-flow.zh-CN.md 3.5 KB
- 📄 custom-fork-sync.md 3.9 KB
- 📄 custom-fork-sync.zh-CN.md 4.2 KB
- 📄 installation.md 931 B
- 📄 installation.zh-CN.md 851 B
- 📄 project-overview.md 1.6 KB
- 📄 project-overview.zh-CN.md 1.2 KB
- 📄 prompt-guide.md 2.1 KB
- 📄 prompt-guide.zh-CN.md 2.1 KB
- 📄 README.md 889 B
- 📄 README.zh-CN.md 773 B
- 📄 skills-installation.md 947 B
- 📄 skills-installation.zh-CN.md 1.0 KB
- 📄 stitch-plugin-roadmap.zh-CN.md 3.5 KB
- 📄 stitch-plugin-spec.zh-CN.md 25.8 KB
- 📄 upstream-brand-protection.md 2.8 KB
- 📄 upstream-brand-protection.zh-CN.md 2.7 KB
- 📄 usage.md 3.8 KB
- 📄 usage.zh-CN.md 3.1 KB
- 📄 version-bump.zh-CN.md 2.1 KB
📁 scripts/
- 📄 apply-ospec-branding.js 3.3 KB
- 📄 postinstall.js 1.1 KB
- 📄 release-smoke.js 7.4 KB
- 📄 setup-custom-fork.js 5.2 KB
- 📄 sync-upstream.js 7.7 KB
- 📄 sync-version.js 1.7 KB
📄 .gitattributes 181 B
📄 .gitignore 89 B
📄 build-index-auto.js 60 B
📄 LICENSE 1.0 KB
📄 package-lock.json 162.9 KB
📄 package.json 2.3 KB
📄 README.md 12.3 KB
📄 README.zh-CN.md 12.4 KB
📄 SKILL.md 9.4 KB
📄 skill.yaml 7.4 KB

SKILL.md

---
name: ospec
tags: [cli, workflow, automation, typescript, ospec, bootstrap]
---

# OSpec CLI

Protocol-shell-first OSpec workflow for initialization, project knowledge backfill, and change execution.

## Default Entry

When the user says something short like:

- `使用 ospec 初始化项目`
- `使用 ospec 初始化这个目录`
- `use ospec to initialize this directory`
- `use ospec to inspect and initialize this repo`

expand it internally as:

1. inspect the target directory
2. initialize the OSpec protocol shell if needed
3. explicitly backfill the project knowledge layer only when needed
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 status [path]`
2. if the directory is uninitialized or missing protocol-shell assets, run `ospec init [path]`
3. verify the actual filesystem result before claiming initialization is complete

Never replace `ospec init` with manual directory creation or a hand-written approximation.

Do not say initialization is complete unless the protocol-shell assets actually exist on disk.

Required protocol-shell 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`

During plain init, do not report `docs/SKILL.md`, `src/SKILL.md`, `tests/SKILL.md`, or business scaffold as if they were part of protocol-shell 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 directory.
```

### 2. Standard Prompt

Use when you want short prompts but still want anti-drift guardrails.

```text
Use ospec to inspect and initialize this directory according to current OSpec rules.
```

### 3. Guardrail Prompt

Use when the model is likely to over-assume frameworks or over-create assets.

```text
Use ospec for this directory. Default to protocol-shell init first, do not assume a web template, do not apply business scaffold during init, and do not create the first change unless explicitly requested.
```

### 4. Knowledge-Backfill Prompt

Use when the protocol shell already exists and the project knowledge layer is still incomplete.

```text
Use ospec to backfill the project knowledge layer for this directory. Focus on docs, layered skills, and index state. 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 treat bootstrap as auto-change creation.
```

### 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` creates the protocol shell only
- `ospec docs generate` backfills project knowledge only
- when the user asks to initialize, execute the CLI init command and verify the protocol-shell 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
- 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 to create a change
- do not enter queue mode unless the user explicitly asks for queue behavior
- treat presets as planning defaults, not as init-time templates
- use the CLI commands for inspection and progress review, not ad-hoc filesystem edits

## What The CLI Manages

This CLI now covers:

- protocol-shell initialization
- project knowledge backfill
- layered skill files
- execution-layer change workflow
- CLI inspection
- preset-based planning defaults
- explicit business scaffold generation for supported presets
- Codex and Claude Code skill install and sync checks

## Canonical Execution Files

Treat these as the source of truth for active delivery work:

- `.skillrc`
- `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 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 skill install
ospec skill status-claude
ospec skill install-claude
```

The default `ospec skill install` and `ospec skill install-claude` commands now install a OSpec skill suite:

- `ospec`
- `ospec-init`
- `ospec-inspect`
- `ospec-backfill`
- `ospec-change`
- `ospec-verify`
- `ospec-archive`
- `ospec-finalize`

Preferred execution order for a new directory:

```bash
ospec status [path]
ospec init [path]
ospec docs generate [path]
ospec new <change-name> [path]
```

For plain init, stop after `ospec init [path]` and verify the protocol-shell assets. Do not silently continue into docs generation unless the user explicitly wants knowledge backfill.

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 first
- keep initialization minimal
- allow the project to stay empty except for OSpec protocol assets
- 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

For this repository itself, also treat these as standard regression checks when behavior changes:

1. `npm run build`
2. `npm run test:run`
3. `npm run release:smoke`

## Supported First-Party Presets

If the request matches a supported preset, prefer that preset instead of inventing a new layout in free text.

- `official-site`: official website, docs center, blog/changelog, admin CMS, auth
- `nextjs-web`: standard Next.js web product with account/auth/API boundaries

Remember: preset choice only supplies planning defaults. It does not turn plain init into template landing.

## Skill Installation

To sync the latest ospec skill into local AI clients, prefer:

1. `ospec skill status`
2. `ospec skill install` when the Codex package is missing or out of sync
3. `ospec skill status-claude`
4. `ospec skill install-claude` when the Claude Code package is missing or out of sync

The default install targets are:

- `~/.codex/skills/ospec`
- `~/.claude/skills/ospec`

Use `$ospec` as the preferred skill name in prompts.

`$ospec-cli` should only be treated as a legacy compatibility alias.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

ospec

Directory Structure

SKILL.md

Report

Notice