ospec

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

Document-driven OSpec workflow for AI-assisted development with change-ready initialization, execution, validation, and archive readiness.

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

Directory Structure

Current level: tree/main/

📁 .github/
- 📁 workflows/
  - 📄 publish-npm.yml 1.7 KB
- 📄 release.yml 820 B
📁 .ospec/
- 📁 templates/
  - 📁 hooks/
    
    📄 post-merge 457 B
    
    📄 pre-commit 457 B
- 📄 asset-sources.json 13.8 KB
📁 agents/
- 📄 openai.yaml 637 B
📁 assets/
- 📁 for-ai/
  - 📁 ar/
    
    📄 ai-guide.md 6.0 KB
    
    📄 execution-protocol.md 5.1 KB
  - 📁 en-US/
    
    📄 ai-guide.md 6.1 KB
    
    📄 execution-protocol.md 5.2 KB
  - 📁 ja-JP/
    
    📄 ai-guide.md 5.0 KB
    
    📄 execution-protocol.md 4.1 KB
  - 📁 zh-CN/
    
    📄 ai-guide.md 6.0 KB
    
    📄 execution-protocol.md 5.1 KB
- 📁 git-hooks/
  - 📄 post-merge 457 B
  - 📄 pre-commit 457 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/
  - 📁 ar/
    
    📄 development-guide.md 1.3 KB
    
    📄 naming-conventions.md 1.5 KB
    
    📄 skill-conventions.md 1.6 KB
    
    📄 workflow-conventions.md 1.8 KB
  - 📁 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
  - 📁 ja-JP/
    
    📄 development-guide.md 1015 B
    
    📄 naming-conventions.md 1.3 KB
    
    📄 skill-conventions.md 1.2 KB
    
    📄 workflow-conventions.md 1.6 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.1 KB
  - 📄 FeatureUpdater.d.ts.map 1.0 KB
  - 📄 FeatureUpdater.js 5.4 KB
  - 📄 FeatureUpdater.js.map 3.5 KB
  - 📄 index.d.ts 724 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.3 KB
  - 📄 StatePersistence.d.ts.map 1.1 KB
  - 📄 StatePersistence.js 5.0 KB
  - 📄 StatePersistence.js.map 3.4 KB
- 📁 cli/
  - 📁 commands/
    
    📄 config.d.ts 54 B
    
    📄 config.d.ts.map 136 B
    
    📄 config.js 68 B
    
    📄 config.js.map 135 B
    
    📄 feature.d.ts 65 B
    
    📄 feature.d.ts.map 138 B
    
    📄 feature.js 79 B
    
    📄 feature.js.map 137 B
    
    📄 index.d.ts 61 B
    
    📄 index.d.ts.map 134 B
    
    📄 index.js 75 B
    
    📄 index.js.map 133 B
    
    📄 project.d.ts 65 B
    
    📄 project.d.ts.map 138 B
    
    📄 project.js 79 B
    
    📄 project.js.map 137 B
    
    📄 validate.d.ts 58 B
    
    📄 validate.d.ts.map 140 B
    
    📄 validate.js 72 B
    
    📄 validate.js.map 139 B
  - 📄 index.d.ts 55 B
  - 📄 index.d.ts.map 122 B
  - 📄 index.js 69 B
  - 📄 index.js.map 121 B
- 📁 commands/
  - 📄 ArchiveCommand.d.ts 472 B
  - 📄 ArchiveCommand.d.ts.map 495 B
  - 📄 ArchiveCommand.js 14.2 KB
  - 📄 ArchiveCommand.js.map 6.5 KB
  - 📄 BaseCommand.d.ts 702 B
  - 📄 BaseCommand.d.ts.map 663 B
  - 📄 BaseCommand.js 964 B
  - 📄 BaseCommand.js.map 773 B
  - 📄 BatchCommand.d.ts 168 B
  - 📄 BatchCommand.d.ts.map 284 B
  - 📄 BatchCommand.js 1.6 KB
  - 📄 BatchCommand.js.map 1.3 KB
  - 📄 ChangesCommand.d.ts 107 B
  - 📄 ChangesCommand.js 3.6 KB
  - 📄 DocsCommand.d.ts 168 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 911 B
  - 📄 index.d.ts.map 764 B
  - 📄 index.js 3.7 KB
  - 📄 index.js.map 653 B
  - 📄 IndexCommand.d.ts 169 B
  - 📄 IndexCommand.d.ts.map 279 B
  - 📄 IndexCommand.js 2.6 KB
  - 📄 IndexCommand.js.map 2.2 KB
  - 📄 InitCommand.d.ts 147 B
  - 📄 InitCommand.d.ts.map 262 B
  - 📄 InitCommand.js 5.5 KB
  - 📄 InitCommand.js.map 1.2 KB
  - 📄 NewCommand.d.ts 344 B
  - 📄 NewCommand.d.ts.map 280 B
  - 📄 NewCommand.js 15.1 KB
  - 📄 NewCommand.js.map 2.3 KB
  - 📄 PluginsCommand.d.ts 2.0 KB
  - 📄 PluginsCommand.js 129.4 KB
  - 📄 ProgressCommand.d.ts 155 B
  - 📄 ProgressCommand.d.ts.map 271 B
  - 📄 ProgressCommand.js 4.3 KB
  - 📄 ProgressCommand.js.map 2.7 KB
  - 📄 QueueCommand.d.ts 282 B
  - 📄 QueueCommand.js 5.7 KB
  - 📄 RunCommand.d.ts 331 B
  - 📄 RunCommand.js 7.5 KB
  - 📄 SkillCommand.d.ts 1.0 KB
  - 📄 SkillCommand.d.ts.map 695 B
  - 📄 SkillCommand.js 27.1 KB
  - 📄 SkillCommand.js.map 12.7 KB
  - 📄 SkillsCommand.d.ts 170 B
  - 📄 SkillsCommand.d.ts.map 281 B
  - 📄 SkillsCommand.js 3.3 KB
  - 📄 SkillsCommand.js.map 2.7 KB
  - 📄 StatusCommand.d.ts 190 B
  - 📄 StatusCommand.d.ts.map 290 B
  - 📄 StatusCommand.js 9.2 KB
  - 📄 StatusCommand.js.map 4.6 KB
  - 📄 UpdateCommand.d.ts 251 B
  - 📄 UpdateCommand.js 19.6 KB
  - 📄 VerifyCommand.d.ts 153 B
  - 📄 VerifyCommand.d.ts.map 266 B
  - 📄 VerifyCommand.js 12.5 KB
  - 📄 VerifyCommand.js.map 5.7 KB
  - 📄 WorkflowCommand.d.ts 309 B
  - 📄 WorkflowCommand.d.ts.map 328 B
  - 📄 WorkflowCommand.js 6.0 KB
  - 📄 WorkflowCommand.js.map 3.2 KB
- 📁 core/
  - 📄 constants.d.ts 1.1 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 103 B
  - 📄 index.d.ts.map 184 B
  - 📄 index.js 914 B
  - 📄 index.js.map 174 B
  - 📄 types.d.ts 9.7 KB
  - 📄 types.d.ts.map 5.8 KB
  - 📄 types.js 76 B
  - 📄 types.js.map 110 B
- 📁 presets/
  - 📄 ProjectPresets.d.ts 1.7 KB
  - 📄 ProjectPresets.d.ts.map 1.5 KB
  - 📄 ProjectPresets.js 19.7 KB
  - 📄 ProjectPresets.js.map 5.7 KB
- 📁 scaffolds/
  - 📄 ProjectScaffoldPresets.d.ts 1.0 KB
  - 📄 ProjectScaffoldPresets.d.ts.map 893 B
  - 📄 ProjectScaffoldPresets.js 9.2 KB
  - 📄 ProjectScaffoldPresets.js.map 5.1 KB
- 📁 services/
  - 📁 templates/
    
    📄 ExecutionTemplateBuilder.d.ts 636 B
    
    📄 ExecutionTemplateBuilder.d.ts.map 615 B
    
    📄 ExecutionTemplateBuilder.js 16.5 KB
    
    📄 ExecutionTemplateBuilder.js.map 5.7 KB
    
    📄 ProjectTemplateBuilder.d.ts 2.7 KB
    
    📄 ProjectTemplateBuilder.d.ts.map 2.2 KB
    
    📄 ProjectTemplateBuilder.js 84.1 KB
    
    📄 ProjectTemplateBuilder.js.map 20.5 KB
    
    📄 TemplateBuilderBase.d.ts 1.3 KB
    
    📄 TemplateBuilderBase.d.ts.map 1.0 KB
    
    📄 TemplateBuilderBase.js 3.8 KB
    
    📄 TemplateBuilderBase.js.map 2.7 KB
    
    📄 TemplateInputFactory.d.ts 897 B
    
    📄 TemplateInputFactory.d.ts.map 763 B
    
    📄 TemplateInputFactory.js 19.2 KB
    
    📄 TemplateInputFactory.js.map 11.8 KB
    
    📄 templateTypes.d.ts 3.0 KB
    
    📄 templateTypes.d.ts.map 2.8 KB
    
    📄 templateTypes.js 76 B
    
    📄 templateTypes.js.map 143 B
  - 📄 ConfigManager.d.ts 629 B
  - 📄 ConfigManager.d.ts.map 668 B
  - 📄 ConfigManager.js 21.3 KB
  - 📄 ConfigManager.js.map 2.6 KB
  - 📄 FeatureManager.d.ts 74 B
  - 📄 FeatureManager.d.ts.map 145 B
  - 📄 FeatureManager.js 88 B
  - 📄 FeatureManager.js.map 144 B
  - 📄 FileService.d.ts 823 B
  - 📄 FileService.d.ts.map 1.1 KB
  - 📄 FileService.js 4.9 KB
  - 📄 FileService.js.map 3.5 KB
  - 📄 index.d.ts 2.5 KB
  - 📄 index.d.ts.map 1.9 KB
  - 📄 index.js 8.1 KB
  - 📄 index.js.map 2.0 KB
  - 📄 IndexBuilder.d.ts 465 B
  - 📄 IndexBuilder.d.ts.map 521 B
  - 📄 IndexBuilder.js 5.4 KB
  - 📄 IndexBuilder.js.map 4.8 KB
  - 📄 Logger.d.ts 466 B
  - 📄 Logger.d.ts.map 616 B
  - 📄 Logger.js 1.3 KB
  - 📄 Logger.js.map 1.4 KB
  - 📄 ProjectAssetRegistry.d.ts 529 B
  - 📄 ProjectAssetRegistry.d.ts.map 563 B
  - 📄 ProjectAssetRegistry.js 4.6 KB
  - 📄 ProjectAssetRegistry.js.map 1.8 KB
  - 📄 ProjectAssetService.d.ts 1.7 KB
  - 📄 ProjectAssetService.d.ts.map 1.3 KB
  - 📄 ProjectAssetService.js 10.5 KB
  - 📄 ProjectAssetService.js.map 7.1 KB
  - 📄 ProjectScaffoldCommandService.d.ts 2.4 KB
  - 📄 ProjectScaffoldCommandService.d.ts.map 2.2 KB
  - 📄 ProjectScaffoldCommandService.js 8.9 KB
  - 📄 ProjectScaffoldCommandService.js.map 4.6 KB
  - 📄 ProjectScaffoldService.d.ts 1.7 KB
  - 📄 ProjectScaffoldService.d.ts.map 1.5 KB
  - 📄 ProjectScaffoldService.js 24.2 KB
  - 📄 ProjectScaffoldService.js.map 10.5 KB
  - 📄 ProjectService.d.ts 9.2 KB
  - 📄 ProjectService.d.ts.map 6.6 KB
  - 📄 ProjectService.js 118.5 KB
  - 📄 ProjectService.js.map 62.3 KB
  - 📄 QueueService.d.ts 909 B
  - 📄 QueueService.js 6.7 KB
  - 📄 RunService.d.ts 1.6 KB
  - 📄 RunService.js 21.0 KB
  - 📄 SkillParser.d.ts 771 B
  - 📄 SkillParser.d.ts.map 636 B
  - 📄 SkillParser.js 2.9 KB
  - 📄 SkillParser.js.map 2.6 KB
  - 📄 StateManager.d.ts 784 B
  - 📄 StateManager.d.ts.map 715 B
  - 📄 StateManager.js 4.6 KB
  - 📄 StateManager.js.map 1.9 KB
  - 📄 TemplateEngine.d.ts 3.6 KB
  - 📄 TemplateEngine.d.ts.map 2.9 KB
  - 📄 TemplateEngine.js 5.4 KB
  - 📄 TemplateEngine.js.map 4.3 KB
  - 📄 TemplateGenerator.d.ts 1.3 KB
  - 📄 TemplateGenerator.d.ts.map 1.0 KB
  - 📄 TemplateGenerator.js 9.3 KB
  - 📄 TemplateGenerator.js.map 4.6 KB
  - 📄 ValidationService.d.ts 429 B
  - 📄 ValidationService.d.ts.map 418 B
  - 📄 ValidationService.js 1.2 KB
  - 📄 ValidationService.js.map 975 B
  - 📄 Validator.d.ts 51 B
  - 📄 Validator.d.ts.map 135 B
  - 📄 Validator.js 65 B
  - 📄 Validator.js.map 134 B
- 📁 tools/
  - 📄 build-index.js 23.6 KB
- 📁 utils/
  - 📄 DateUtils.d.ts 332 B
  - 📄 DateUtils.d.ts.map 341 B
  - 📄 DateUtils.js 1.1 KB
  - 📄 DateUtils.js.map 1.2 KB
  - 📄 helpers.d.ts 153 B
  - 📄 helpers.d.ts.map 128 B
  - 📄 helpers.js 686 B
  - 📄 helpers.js.map 127 B
  - 📄 index.d.ts 118 B
  - 📄 index.d.ts.map 185 B
  - 📄 index.js 929 B
  - 📄 index.js.map 175 B
  - 📄 logger.d.ts 51 B
  - 📄 logger.d.ts.map 126 B
  - 📄 logger.js 65 B
  - 📄 logger.js.map 125 B
  - 📄 path.d.ts 57 B
  - 📄 path.d.ts.map 122 B
  - 📄 path.js 71 B
  - 📄 path.js.map 121 B
  - 📄 PathUtils.d.ts 460 B
  - 📄 PathUtils.d.ts.map 489 B
  - 📄 PathUtils.js 2.5 KB
  - 📄 PathUtils.js.map 1002 B
  - 📄 StringUtils.d.ts 524 B
  - 📄 StringUtils.d.ts.map 507 B
  - 📄 StringUtils.js 1.1 KB
  - 📄 StringUtils.js.map 1.1 KB
  - 📄 subcommandHelp.d.ts 535 B
  - 📄 subcommandHelp.d.ts.map 431 B
  - 📄 subcommandHelp.js 5.8 KB
  - 📄 subcommandHelp.js.map 764 B
- 📁 workflow/
  - 📄 ArchiveGate.d.ts 924 B
  - 📄 ArchiveGate.d.ts.map 910 B
  - 📄 ArchiveGate.js 4.2 KB
  - 📄 ArchiveGate.js.map 3.1 KB
  - 📄 ConfigurableWorkflow.d.ts 2.4 KB
  - 📄 ConfigurableWorkflow.d.ts.map 1.6 KB
  - 📄 ConfigurableWorkflow.js 6.5 KB
  - 📄 ConfigurableWorkflow.js.map 5.0 KB
  - 📄 HookSystem.d.ts 1022 B
  - 📄 HookSystem.d.ts.map 997 B
  - 📄 HookSystem.js 1.7 KB
  - 📄 HookSystem.js.map 1.9 KB
  - 📄 index.d.ts 1.1 KB
  - 📄 index.d.ts.map 832 B
  - 📄 index.js 3.4 KB
  - 📄 index.js.map 534 B
  - 📄 IndexRegenerator.d.ts 1.0 KB
  - 📄 IndexRegenerator.d.ts.map 978 B
  - 📄 IndexRegenerator.js 5.4 KB
  - 📄 IndexRegenerator.js.map 3.4 KB
  - 📄 PluginWorkflowComposer.d.ts 3.5 KB
  - 📄 PluginWorkflowComposer.js 8.2 KB
  - 📄 SkillUpdateEngine.d.ts 899 B
  - 📄 SkillUpdateEngine.d.ts.map 1.0 KB
  - 📄 SkillUpdateEngine.js 4.1 KB
  - 📄 SkillUpdateEngine.js.map 2.4 KB
  - 📄 VerificationSystem.d.ts 816 B
  - 📄 VerificationSystem.d.ts.map 850 B
  - 📄 VerificationSystem.js 4.1 KB
  - 📄 VerificationSystem.js.map 3.1 KB
  - 📄 WorkflowEngine.d.ts 664 B
  - 📄 WorkflowEngine.d.ts.map 665 B
  - 📄 WorkflowEngine.js 2.3 KB
  - 📄 WorkflowEngine.js.map 2.0 KB
- 📄 .npmignore 9 B
- 📄 cli.d.ts 30 B
- 📄 cli.d.ts.map 100 B
- 📄 cli.js 16.1 KB
- 📄 cli.js.map 4.7 KB
- 📄 index.d.ts 229 B
- 📄 index.d.ts.map 260 B
- 📄 index.js 1.1 KB
- 📄 index.js.map 218 B
📁 docs/
- 📄 checkpoint-plugin-spec.ar.md 17.4 KB
- 📄 checkpoint-plugin-spec.ja.md 16.5 KB
- 📄 checkpoint-plugin-spec.md 12.3 KB
- 📄 checkpoint-plugin-spec.zh-CN.md 23.6 KB
- 📄 installation.ar.md 1.2 KB
- 📄 installation.ja.md 1.0 KB
- 📄 installation.md 826 B
- 📄 installation.zh-CN.md 824 B
- 📄 issue-automation.md 11.0 KB
- 📄 project-overview.ar.md 3.6 KB
- 📄 project-overview.ja.md 3.9 KB
- 📄 project-overview.md 2.7 KB
- 📄 project-overview.zh-CN.md 2.5 KB
- 📄 prompt-guide.ar.md 3.9 KB
- 📄 prompt-guide.ja.md 3.2 KB
- 📄 prompt-guide.md 2.5 KB
- 📄 prompt-guide.zh-CN.md 2.4 KB
- 📄 README.ar.md 16.2 KB
- 📄 README.ja.md 13.5 KB
- 📄 README.zh-CN.md 12.3 KB
- 📄 skills-installation.ar.md 1.2 KB
- 📄 skills-installation.ja.md 1.7 KB
- 📄 skills-installation.md 1.3 KB
- 📄 skills-installation.zh-CN.md 1.3 KB
- 📄 stitch-plugin-spec.ar.md 8.2 KB
- 📄 stitch-plugin-spec.ja.md 7.9 KB
- 📄 stitch-plugin-spec.md 6.3 KB
- 📄 stitch-plugin-spec.zh-CN.md 28.7 KB
- 📄 usage.ar.md 5.4 KB
- 📄 usage.ja.md 6.7 KB
- 📄 usage.md 5.7 KB
- 📄 usage.zh-CN.md 4.8 KB
📁 scripts/
- 📄 dev-watch.js 1.5 KB
- 📄 postinstall.js 1.3 KB
- 📄 release-cut.js 7.5 KB
- 📄 release-notes.js 13.8 KB
- 📄 release-smoke.js 12.1 KB
- 📄 release-upload-notes.js 8.1 KB
- 📄 strip-sourcemap-refs.js 2.2 KB
- 📄 sync-version.js 1.4 KB
📁 tests/
- 📄 build-index-tooling-migration.test.mjs 7.8 KB
- 📄 change-markdown-links.test.mjs 2.9 KB
- 📄 document-language-detection.test.mjs 3.8 KB
- 📄 release-notes.test.mjs 4.7 KB
- 📄 release-upload-notes.test.mjs 1.8 KB
- 📄 tasks-template-format.test.mjs 1.3 KB
- 📄 tasks-validation-structure.test.mjs 8.3 KB
📄 .gitignore 98 B
📄 LICENSE 1.0 KB
📄 package-lock.json 162.9 KB
📄 package.json 3.0 KB
📄 README.md 13.4 KB
📄 RELEASING.md 3.8 KB
📄 SKILL.md 9.6 KB
📄 skill.yaml 8.4 KB

SKILL.md

---
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`
- `.ospec/tools/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

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

ospec

Directory Structure

SKILL.md

Report

Notice