robsonprod/portfolio

OpenSpec 변경 사항의 작업을 구현합니다.

스토어 선택: 사용자가 스토어(이 머신에 등록된 독립적인 OpenSpec 저장소)를 언급하거나 작업이 특정 스토어에 속하는 경우, openspec store list --json을 실행하여 등록된 스토어 ID를 확인한 후, 사양(spec) 및 변경 사항(change)을 읽고 쓰는 명령어(new change, status, instructions, list, show, validate, archive, doctor, context, schemas, view)에 --store <id> 플래그를 전달하세요. 스토어가 선택되면 해당 워크플로우 전체에서 --store <id>를 고정적으로 사용합니다. 아래 명령어들의 스코프 없는 예시는 축약형입니다. 실행 전에 반드시 플래그를 추가하세요. 예를 들어, openspec status --change "<name>" --json --store "<id>"와 같이 실행하고, 축약형을 그대로 사용하지 마세요. 다른 명령어는 이 플래그를 사용하지 않습니다. 명령어가 출력하는 힌트에는 이미 플래그가 포함되어 있으므로, 후속 작업에서도 그대로 유지하세요. 스토어가 없으면 명령어는 가장 가까운 로컬 openspec/ 루트에서 작동합니다.

프로젝트 확인: 이 단계는 이미 OpenSpec을 사용하는 프로젝트를 가정합니다. 무언가를 쓰는 첫 번째 단계(new change, archive, sync specs, 또는 아티팩트 파일 작성) 전에, 프로젝트에 루트가 있는지 확인하세요. openspec list --json (스토어가 선택된 경우 --store <id>를 함께 사용, 스토어가 곧 루트이기 때문)을 실행하고 root 값을 읽으세요. root 객체가 있으면 프로젝트가 설정된 것입니다. "root": null은 설정되지 않았음을 의미합니다. 즉, 여기에 openspec/ 디렉토리가 없으며, openspec new change와 같은 쓰기 명령이 부작용(side effect)으로 디렉토리를 생성할 수 있습니다. 이 명령은 또한 0이 아닌 종료 코드를 반환하는데, 이는 CLI 자체의 오류가 아니라 설정되지 않았다는 신호이므로, JSON을 읽어서 판단하고 재시도하거나 우회하지 마세요.

"root": null이 설정 문제가 아닌 경우: status 오류 메시지가 Declared in 또는 Invalid store declaration in으로 시작하면서 이 프로젝트의 openspec/config.yaml (또는 config.yml) 파일을 언급하는 경우, 프로젝트는 선언한 스토어를 통해 OpenSpec을 사용하지만 이 머신에서 해당 스토어를 확인할 수 없습니다 (스토어가 등록되지 않았거나 store: 줄이 잘못됨). 이 경우 초기화되지 않은 것으로 간주하지 말고 아래 분기를 건너뛰세요. 쓰기 작업을 시작하기 전에 중단하고 사용자에게 해당 오류의 message와 fix를 표시하세요.

그 외에 루트가 없는 경우, 이 워크플로우에 어떻게 도달했는지에 따라 달라집니다:

• 자동 선택: 사용자가 OpenSpec, 이 스킬, 또는 슬래시 명령어를 언급하지 않은 상태에서 당신이 스스로 이 워크플로우를 선택한 경우입니다. OpenSpec 사용을 중단하고, OpenSpec이 설치되지 않은 것처럼 요청을 정상적으로 처리하세요. 사용자에게 설정을 요청하거나 OpenSpec 설정을 언급하지 마세요.
• 명시적 OpenSpec 요청: 사용자가 OpenSpec, 이 스킬, 또는 슬래시 명령어를 직접 언급한 경우입니다. 쓰기 작업 전에 중단하고 다음 중 어떻게 진행할지 물어보세요: 이 프로젝트 설정 (openspec init), 이미 가지고 있는 스토어 대상 지정 (--store <id>), 또는 이 요청에 대해 OpenSpec 없이 계속 진행. 답변을 기다리세요.

두 분기 모두에서, 루트를 부작용으로 절대 생성하지 마세요: 사용자가 요청하기 전까지 openspec init을 실행하지 말고, openspec/ 파일을 직접 생성하지 말며, 명령어가 생성하도록 방치하지 마세요.

입력: 선택적으로 변경 사항 이름을 지정할 수 있습니다 (예: /opsx:apply add-auth). 생략된 경우 대화 컨텍스트에서 유추할 수 있는지 확인하세요. 모호하거나 명확하지 않은 경우 사용 가능한 변경 사항을 알려달라고 반드시 요청하세요.

단계

1. 변경 사항 선택

   이름이 제공되면 그것을 사용하세요. 그렇지 않으면:

   • 사용자가 변경 사항을 언급했다면 대화 컨텍스트에서 유추
   • 활성화된 변경 사항이 하나만 있으면 자동 선택
   • 모호한 경우 openspec list --json을 실행하여 사용 가능한 변경 사항을 확인하고 사용자에게 하나를 선택하도록 요청

   항상 알립니다: "다음 변경 사항을 사용합니다: " 및 재정의 방법 (예: /opsx:apply <other>).

2. 스키마를 이해하기 위해 상태 확인

   openspec status --change "<name>" --json
   

   JSON을 파싱하여 다음을 이해합니다:

   • schemaName: 사용 중인 워크플로우 (예: "spec-driven")
   • planningHome, changeRoot, actionContext: 계획 범위 및 편집 제약 조건
   • 어떤 아티팩트에 작업이 포함되어 있는지 (일반적으로 spec-driven의 경우 "tasks", 다른 스키마는 status 확인)

3. 적용 지침 가져오기

   openspec instructions apply --change "<name>" --json
   

   반환값:

   • contextFiles: 아티팩트 ID -> 구체적인 파일 경로 배열 (스키마에 따라 다름 - proposal/specs/design/tasks 또는 spec/tests/implementation/docs 일 수 있음)
   • 진행 상황 (전체, 완료, 남음)
   • 상태, 소스 경로 및 소스 줄이 포함된 작업 목록
   • 현재 상태 기반 동적 지침
   • 선택적 context: 선택된 루트의 현재 필수 프로젝트 지침 입력
   • 선택적 operationGuidance: 현재 적용을 위한 권장 지침
   • missingArtifacts (있는 경우): 출력이 없는 필수 아티팩트 ID

   상태 처리:

   • state: "blocked"인 경우: 메시지를 표시하고 구현을 일시 중지합니다.
     • missingArtifacts가 비어 있지 않으면: 누락된 아티팩트를 완료할 것을 제안합니다. openspec status --change "<name>" --json을 실행하고, 다음 ready 아티팩트를 선택한 후 (skipped 또는 blocked 제외), openspec instructions "<artifact-id>" --change "<name>" --json을 사용하여 해당 규칙과 템플릿을 가져옵니다. 두 명령어 모두 선택한 --store <id>를 유지합니다.
     • 그렇지 않으면 CLI 지침에 따라 기존 계획 아티팩트에서 스키마가 구성한 추적 파일을 생성하거나 복구합니다. 차단된 상태에서 다른 아티팩트가 준비되었다고 가정하거나 구현을 시작하지 마세요.
   • state: "all_done"인 경우: 모든 추적된 작업이 완료되었음을 보고하고 보관 전에 적절한 검토 또는 확인을 제안합니다.
   • 그 외의 경우: 구현을 진행합니다.

   context를 필수 프롬프트 수준 입력으로 취급합니다. 읽고 고려하며, 구현 중 관련 프로젝트 사실, 관습 및 제약 조건을 적용합니다. operationGuidance를 선택적 추가 조언으로 취급합니다. 모든 항목을 읽고 고려하며, 적용 가능하고 내장 워크플로우와 호환되는 항목을 따릅니다.

   두 필드를 CLI가 반환한 상태, 누락된 아티팩트, 작업, 진행률, contextFiles 및 내장 instruction과 분리하여 유지합니다. 이는 작업 완료의 증거가 아니며, 내장 지침을 대체하지 않으며, 차단된 상태를 우회하는 것을 허용하지 않습니다. context가 내장 지침, 명시적 사용자 선택, 또는 CLI 제어 값과 충돌하는 경우 충돌을 보고하고 제어 값을 유지합니다. guidance가 적용 불가능하거나 이러한 제어 입력과 충돌하는 경우 따르지 말고 이유를 설명합니다. 이는 프롬프트 수준의 행동 계약이지 강제 가능한 검사가 아닙니다.

4. 컨텍스트 파일 읽기

   적용 지침 출력의 contextFiles 아래에 나열된 모든 파일 경로를 읽습니다. 파일은 사용 중인 스키마에 따라 다릅니다:

   • spec-driven: proposal, specs, design, tasks
   • 기타 스키마: CLI 출력의 contextFiles를 따릅니다.

   사용자가 별도로 요청하지 않는 한 context 또는 operationGuidance를 구현 파일이나 계획 아티팩트에 그대로 복사하지 마세요.

5. 현재 진행 상황 표시

   다음을 표시합니다:

   • 사용 중인 스키마
   • 진행 상황: "N/M 작업 완료"
   • 남은 작업 개요
   • CLI의 동적 지침

6. 작업 구현 (완료되거나 차단될 때까지 반복)

   각 대기 중인 작업에 대해:

   • 어떤 작업을 진행 중인지 표시
   • 필요한 코드 변경 수행
   • 변경 사항을 최소화하고 집중적으로 유지
   • 편집 전, 반환된 sourcePath 및 line의 체크박스가 여전히 작업 설명과 일치하는지 확인; 일치하지 않으면 적용 지침을 다시 실행하고 새로 고쳐진 위치를 사용
   • 반환된 sourcePath 및 line에서 작업 완료 표시: - [ ] → - [x]
   • 적용 지침을 다시 실행하고 해당 작업이 완료되고 진행 상황이 변경되었는지 확인
   • 다음 작업으로 계속

   다음 경우 일시 중지:

   • 작업이 불명확함 → 명확화 요청
   • 구현 중 설계 문제 발견 → 아티팩트 업데이트 제안
   • 작업이 사양 및 작업 설명 이상의 추가 작업을 필요로 하거나, 지정된 동작을 맞추기 위해 축소, 연기, 예외를 수용하려는 유혹을 느낄 때 → 추가된 범위를 표면화하고 질문; 조용히 흡수하지 마세요
   • 오류 또는 차단 요인 발생 → 보고하고 지침 대기
   • 사용자가 중단

7. 완료 또는 일시 중지 시, 상태 표시

   다음을 표시합니다:

   • 이 세션에서 완료된 작업
   • 전체 진행 상황: "N/M 작업 완료"
   • 모두 완료된 경우: 추적된 작업이 완료되었음을 보고하고 보관 전에 적절한 검토 또는 확인을 제안
   • 일시 중지된 경우: 이유를 설명하고 지침 대기

구현 중 출력

## 구현 중: <change-name> (스키마: <schema-name>)

작업 3/7 진행 중: <task description>
[...구현 진행 중...]
✓ 작업 완료

작업 4/7 진행 중: <task description>
[...구현 진행 중...]
✓ 작업 완료

완료 시 출력

## 구현 완료

**변경 사항:** <change-name>
**스키마:** <schema-name>
**진행 상황:** 7/7 작업 완료 ✓

### 이 세션에서 완료됨
- [x] 작업 1
- [x] 작업 2
...

모든 추적된 작업이 완료되었습니다. 보관 전에 적절히 변경 사항을 검토하거나 확인하세요.
`/opsx:archive`로 이 변경 사항을 보관할 수 있습니다.

일시 중지 시 출력 (문제 발생)

## 구현 일시 중지

**변경 사항:** <change-name>
**스키마:** <schema-name>
**진행 상황:** 4/7 작업 완료

### 발생한 문제
<issue description>

**옵션:**
1. <option 1>
2. <option 2>
3. 다른 접근 방식

어떻게 하시겠습니까?

가드레일

• 완료되거나 차단될 때까지 작업을 계속 진행하세요
• 시작 전에 항상 컨텍스트 파일을 읽으세요 (적용 지침 출력에서)
• 작업이 모호하면 일시 중지하고 구현 전에 질문하세요
• 구현 중 문제가 발견되면 일시 중지하고 아티팩트 업데이트를 제안하세요
• 코드 변경을 각 작업에 최소화하고 집중하세요
• 각 작업 완료 직후 작업 체크박스를 업데이트하세요
• 오류, 차단 요인 또는 불명확한 요구 사항이 있으면 일시 중지 - 추측하지 마세요
• 작업이 사양에 설명된 것 이상의 작업을 필요로 할 때 추가된 범위를 표면화하고 일시 중지 - 절대 지정된 동작을 조용히 축소, 연기 또는 단순화하지 마세요
• 지정된 동작이 완전히 구현된 경우에만 작업을 - [x]로 표시하고, 부분적으로 완료되거나 연기된 경우에는 하지 마세요
• CLI 출력의 contextFiles를 사용하고, 특정 파일 이름을 가정하지 마세요
• 각 작업의 sourcePath와 line을 사용하여 정확한 체크박스를 업데이트하세요
• context나 operation guidance를 작업 완료의 증거로 사용하지 마세요
• 관련 프로젝트 컨텍스트를 적용하고, 제어 워크플로우 입력과의 충돌을 보고하세요
• 모든 guidance 항목을 고려하고; 적용 불가능하거나 충돌하는 조언은 설명하세요
• 런타임 context나 operation guidance를 구현 파일이나 계획 아티팩트에 복사하지 마세요
• CLI가 제어하는 blocked/ready/all-done 동작 및 완료 기준을 유지하세요

유동적 워크플로우 통합

이 스킬은 "변경 사항에 대한 작업" 모델을 지원합니다:

• 언제든지 호출 가능: 모든 아티팩트가 완료되기 전(작업이 존재하는 경우), 부분 구현 후, 다른 작업과 인터리빙하여
• 아티팩트 업데이트 허용: 구현 중 설계 문제가 발견되면 아티팩트 업데이트 제안 - 단계 고정되지 않음, 유동적으로 작업