williamsnieves/landing-factory

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

저장소 선택: 사용자가 저장소(이 머신에 등록된 독립형 OpenSpec 리포)를 지정하거나 작업이 특정 저장소에 속하는 경우, openspec store list --json을 실행하여 등록된 저장소 ID를 확인한 후, 스펙 및 변경 사항을 읽거나 쓰는 명령(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을 실행하고 root 값을 읽어 프로젝트에 루트가 있는지 확인하세요(저장소가 선택된 경우 --store <id>를 추가하세요. 저장소가 루트이기 때문입니다). root 객체는 프로젝트가 설정되었음을 의미합니다. "root": null은 설정되지 않았음을 의미합니다. 즉, 여기에는 openspec/ 디렉토리가 없으며, openspec new change와 같은 쓰기 명령어가 부작용으로 디렉토리를 생성할 수 있습니다. 명령어는 또한 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과 분리하여 유지하세요. 이는 작업 완료 증거가 아니며, 내장 지침을 대체하지 않으며, 차단된 상태를 우회하는 것을 허용하지 않습니다. 컨텍스트가 내장 지침, 명시적 사용자 선택 또는 CLI 제어 값과 충돌하는 경우, 충돌을 보고하고 제어 값을 유지하세요. 지침이 적용 불가능하거나 이러한 제어 입력과 충돌하는 경우, 따르지 말고 이유를 설명하세요. 이는 프롬프트 수준의 동작 계약이며, 강제 가능한 검사가 아닙니다.

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 작업 완료

### 발생한 문제
<문제 설명>

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

어떻게 하시겠습니까?

가드레일

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

유동적 워크플로우 통합

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

• 언제든지 호출 가능: 모든 아티팩트가 완료되기 전(작업이 존재하는 경우), 부분 구현 후, 다른 작업과 혼합하여 사용 가능
• 아티팩트 업데이트 허용: 구현 중 설계 문제가 발견되면 아티팩트 업데이트를 제안할 수 있습니다. 단계가 고정되어 있지 않으며 유연하게 작업합니다.