clawplays/ospec

공식 OSpec CLI 패키지는 @clawplays/ospec-cli이며, 공식 명령어는 ospec입니다. OSpec은 AI 코딩 에이전트(AI coding agents) 및 CLI 워크플로우(workflows)를 위한 사양 주도 개발 (SDD, spec-driven development) 및 문서 주도 개발 (document-driven development)을 지원합니다.

프롬프트 가이드 | 사용법 | 개요 | 설치 | 외부 플러그인 | 플러그인 릴리스 | 이슈

AI 코딩 어시스턴트 (AI coding assistants)는 강력하지만, 채팅 기록에만 존재하는 요구사항은 검사, 검토 및 깔끔하게 종결하기가 어렵습니다. OSpec은 경량 워크플로우 레이어 (workflow layer)를 추가하여, 코드가 작성되기 전과 작업이 배포된 후의 변경 컨텍스트 (change context)를 저장소 (repository)에 유지할 수 있도록 합니다.

• 코드 작성 전 정렬 — 제안, 작업, 상태, 검증 및 검토 내용을 저장소에 가시적으로 유지
• 각 요구사항을 명시적으로 유지 — 기본 경로는 하나의 요구사항을 하나의 활성 변경 사항으로 이동시킴
• 경량화 유지 — init -> change -> verify/finalize 과정을 통해 일반적인 흐름을 짧게 유지
• 기존 어시스턴트 활용 — OSpec은 Codex, Claude Code 및 직접적인 CLI 워크플로우를 위해 구축되었습니다.

npm install -g @clawplays/ospec-cli

공식 패키지: @clawplays/ospec-cli

명령어: ospec

설치 확인: ospec --help

OSpec은 단 3단계만 거칩니다:

• 프로젝트 디렉토리에 OSpec 초기화 (initialize)
• 요구사항, 문서 업데이트 또는 버그 수정을 위한 하나의 변경 사항을 생성하고 진행
• 배포 및 검증이 완료된 후 수락된 변경 사항을 아카이브 (archive)

권장 프롬프트:

OSpec, initialize this project.

Claude / Codex 스킬 모드:

/ospec initialize this project.

커맨드 라인 (Command line)

ospec init .
ospec init . --summary "Internal admin portal for operations"
ospec init . --summary "Internal admin portal for operations" --tech-stack node,react,postgres
...

CLI 참고 사항:

--summary : 생성된 문서에 작성될 프로젝트 개요 텍스트

--tech-stack : node,react,postgres와 같이 쉼표로 구분된 스택 목록

--architecture : 짧은 아키텍처 (architecture) 설명

--document-language : 생성될 문서 언어, en-US, zh-CN, ja-JP 또는 ar 중에서 선택

• AI 우선 언어 결정 순서 (AI-first language resolution order): 대화 중 명시적인 언어 요청 -> 현재 대화 언어 -> .skillrc에 저장된 프로젝트 언어

• CLI 언어 결정 순서 (CLI language resolution order): 명시적인 --document-language

-> .skillrc에 저장된 프로젝트 언어

-> 기존 프로젝트 문서 / 관리되는 for-ai/* 가이드라인 / 에셋 매니페스트 (asset manifest) -> 기본값 en-US로 폴백 (fallback)

• OSpec은 선택된 프로젝트 문서 언어를 .skillrc에 저장하며, 이를 for-ai 가이드라인, ospec new, 그리고 ospec update에서 재사용합니다.

• ospec init으로 초기화된 새 프로젝트는 루트의 .skillrc 및 README.md를 포함하는 중첩된 레이아웃 (nested layout)을 기본값으로 하며, OSpec이 관리하는 파일들은 .ospec/ 아래에 위치합니다.

• 일반적인 초기화 (plain init) 시에는 .ospec/knowledge/src/ 또는 .ospec/knowledge/tests/와 같은 선택적 지식 맵 (knowledge maps)을 생성하지 않습니다. 이러한 디렉토리는 마이그레이션할 기존 레거시 지식 콘텐츠가 이미 프로젝트에 있거나, 향후 명시적인 지식 생성 흐름 (knowledge-generation flows)이 이를 생성할 때만 나타납니다. CLI 명령은 여전히 changes/active/<change-name>과 같은 축약형 (shorthand)을 허용하지만, 중첩된 프로젝트에서의 실제 경로는 .ospec/changes/active/<change-name>입니다.

• 이 값들을 전달하면, OSpec은 프로젝트 문서를 생성할 때 이를 직접 사용합니다.

• 이 값들을 전달하지 않으면, OSpec은 가능한 경우 기존 문서를 재사용하며, 그렇지 않으면 먼저 플레이스홀더 (placeholder) 문서를 생성합니다.

요구사항 전달 (requirement delivery), 문서 업데이트, 리팩터링 (refactors), 그리고 버그 수정 (bug fixes)에 이를 사용하세요.

권장 프롬프트 (Recommended prompt):

OSpec, create and advance a change for this requirement.

Claude / Codex 스킬 모드 (skill mode):

/ospec-change create and advance a change for this requirement.

커맨드 라인 (Command line)

ospec new docs-homepage-refresh .
ospec new fix-login-timeout .
ospec new update-billing-copy .

요구사항이 배포 (deployment), 테스트 (testing), QA, 또는 기타 수락 검사 (acceptance checks)를 통과한 후에는 검증된 변경 사항을 아카이브 (archive) 하세요.

권장 프롬프트 (Recommended prompt):

OSpec, archive this accepted change.

Claude / Codex 스킬 모드 (skill mode):

/ospec archive this accepted change.

커맨드 라인 (Command line)

ospec verify changes/active/<change-name>
ospec finalize changes/active/<change-name>

아카이브 노트 (Archive notes):

• 프로젝트별 배포 (deploy), 테스트 (test), QA 흐름을 먼저 실행하세요
• 활성화된 변경 사항 (active change)이 준비되었는지 확인하려면 ospec verify를 사용하세요
• 인덱스를 재구축 (rebuild indexes)하고 승인된 변경 사항을 아카이브하려면 ospec finalize를 사용하세요 - 새로운 중첩 프로젝트 (nested projects)는 .ospec/changes/archived/YYYY-MM/YYYY-MM-DD/<change-name> 아래에 아카이브됩니다

; CLI shorthand under changes/archived/...는 여전히 작동합니다 - 기존의 플랫 아카이브 (flat archives)는 ospec update에 의해 재구성됩니다

기존 OSpec 프로젝트의 경우, npm으로 CLI를 업그레이드한 후 프로젝트 디렉토리에서 다음을 실행하여 프로젝트의 OSpec 파일들을 갱신하세요:

ospec update

ospec update는 또한 레거시 루트 레벨의 build-index-auto.cjs / build-index-auto.js 툴링을 .ospec/tools/build-index-auto.cjs로 마이그레이션하며, OSpec이 관리하는 훅 엔트리포인트 (hook entrypoints)가 새로운 위치를 사용하도록 갱신합니다.
또한 OSpec의 흔적은 남아있지만 최신 코어 런타임 디렉토리 (core runtime directories)가 누락된 오래된 OSpec 프로젝트를 복구하고, 관리되는 스킬 (managed skills) 및 아카이브 레이아웃 메타데이터를 갱신하며, 이미 활성화된 플러그인 (plugins)을 위한 프로젝트 에셋 (project assets)을 동기화합니다.
.ospec/src/ 또는 .ospec/tests/ 아래에 여전히 레거시 지식 (legacy knowledge)을 보유하고 있는 중첩 프로젝트의 경우, ospec update는 해당 경로들을 .ospec/knowledge/src/ 및 .ospec/knowledge/tests/로 마이그레이션합니다.
이미 활성화된 플러그인에 대해 더 최신의 호환 가능한 npm 패키지 버전이 사용 가능한 경우, ospec update는 해당 글로벌 플러그인 패키지를 자동으로 업그레이드하고 버전 전환을 출력합니다.
이 명령은 CLI 자체를 업그레이드하지 않으며, 플러그인을 활성화하거나 활성/대기 중인 변경 사항 (active / queued changes)을 자동으로 마이그레이션하지 않습니다.
또한 클래식 프로젝트 레이아웃 (classic project layout)을 자동으로 중첩 레이아웃으로 전환하지도 않습니다.
이전의 클래식 프로젝트를 새로운 레이아웃으로 변환하려면 ospec layout migrate --to nested를 명시적으로 실행하세요.

┌─────────────────────────────────────────────────────────────────┐
│ 1. 사용자 요청 (USER REQUEST) │
│ "OSpec, 이 작업을 위한 변경 사항을 생성하고 진행해줘." │
...

개념 (Concept)	의미 (What It Means)
프로토콜 셸 (Protocol Shell)	최소한의 협업 골격: 루트 디렉토리의 .skillrc 및 README.md와 더불어, 변경 상태, SKILL 문서, 인덱스 상태, for-ai/ 가이드라인, 프로젝트 문서를 관리하기 위해 .ospec/ 하위에 관리되는 OSpec 파일들로 구성됩니다.
프로젝트 지식 계층 (Project Knowledge Layer)	docs/project/*와 같은 명시적인 프로젝트 컨텍스트, 계층화된 스킬 (skill) 파일, 그리고 AI가 일관되게 읽을 수 있는 인덱스 상태를 의미합니다.
활성 변경 (Active Change)	하나의 요구사항을 위한 전용 실행 컨테이너로, 통상적으로 proposal.md, tasks.md, state.json, verification.md, review.md를 포함합니다.

변경 준비 초기화 (Change-ready initialization): ospec init 명령은 프로토콜 셸과 기본 프로젝트 지식 문서를 한 번에 생성합니다.

가이드형 초기화 (Guided initialization): AI 지원 초기화는 누락된 요약이나 기술 스택(tech stack)에 대해 한 번 질문할 수 있습니다. 직접적인 CLI 초기화는 컨텍스트가 누락된 경우 플레이스홀더 (placeholder) 문서로 대체됩니다.

안정적인 프로젝트 언어 (Stable project language): 선택된 문서 언어는 .skillrc에 저장되므로, 사용자가 명시적으로 변경하지 않는 한 이후의 가이드라인과 생성된 변경 문서들이 일관성을 유지합니다.

문서 유지보수 (Docs maintenance): ospec docs generate는 나중에 필요할 때 프로젝트 지식 문서를 새로고침하거나 복구합니다.

추적 가능한 요구사항 실행 (Tracked requirement execution): 각 변경 사항은 제안(proposal), 작업(tasks), 상태(state), 검증(verification), 검토(review) 파일들을 정렬된 상태로 유지할 수 있습니다.

큐 도우미 (Queue helpers): queue 및 run 명령은 하나의 활성 변경만으로 충분하지 않을 때 명시적인 다중 변경 실행을 지원합니다.

플러그인 워크플로우 게이트 (Plugin workflow gates): 플러그인 명령은 npm으로 설치된 공식 플러그인을 통해 Stitch 디자인 검토 및 Checkpoint 자동화를 지원합니다.

스킬 관리 (Skill management): Codex 및 Claude Code를 위한 OSpec 스킬을 설치하고 검사할 수 있습니다.

표준 종료 (Standard closeout): finalize는 수동 Git 커밋을 수행하기 전에 변경 사항을 검증하고, 인덱스를 재구축하며, 아카이브합니다.

OSpec은 UI 검토 및 런타임 검증을 위한 플러그인을 지원합니다. 공개적인 흐름은 다음과 같이 단순하게 유지하십시오:

/ospec open Stitch for this project.
/ospec open Checkpoint for this project.

AI / /ospec

흐름(flows), "open Stitch" 또는 "open Checkpoint"와 같은 요청은 다음과 같이 처리되어야 합니다: 플러그인이 이미 전역(globally)으로 설치되어 있는지 확인하고, 누락된 경우에만 설치한 다음 현재 프로젝트에서 활성화합니다.

커맨드 라인(Command line) 폴백(fallback):

ospec plugins list
ospec plugins install stitch
ospec plugins enable stitch .
...

공식 npm 플러그인 패키지:

@clawplays/ospec-plugin-stitch

@clawplays/ospec-plugin-checkpoint

플러그인이 활성화된 후, 해당 플러그인의 상세 설정 문서(setup docs)는 .ospec/plugins/<plugin>/docs/로 동기화됩니다.

유지 관리자(Maintainers)는 docs/plugin-release.md에서 플러그인 게시 및 자동화에 관한 세부 정보를 확인할 수 있습니다.

• 프롬프트 가이드 (Prompt Guide)
• 사용법 (Usage)
• 프로젝트 개요 (Project Overview)
• 설치 (Installation)
• 스킬 설치 (Skills Installation)
• 외부 플러그인 (External Plugins)
• 플러그인 릴리스 (Plugin Release)

dist/ 컴파일된 CLI 런타임 (Compiled CLI runtime)
assets/ 관리되는 프로토콜 자산, 훅(hooks) 및 스킬 페이로드 (Managed protocol assets, hooks, and skill payloads)
docs/ 공개 문서 (Public documentation)
...

이 프로젝트는 MIT 라이선스(MIT License) 하에 배포됩니다.