Squashed '.vendor/myagent-kit/' content from commit 96defc9

git-subtree-dir: .vendor/myagent-kit git-subtree-split: 96defc92f92d617a80f7b0f54e998ce4c25f631b
2026-04-13 23:25:23 +09:00
commit acd1bab8f2
19 changed files with 1058 additions and 0 deletions
@@ -0,0 +1,152 @@
+# myagent-kit
+
+Reusable Copilot Development workflow assets.
+
+## Contents
+- `base/.github/prompts`: reusable prompts
+- `base/.github/instructions`: reusable file instructions
+- `base/.github/ISSUE_TEMPLATE`: reusable issue templates
+- `base/.github/copilot-instructions.md`: managed Copilot baseline gate template (opt-in merge)
+- `base/.github/pull_request_template.md`: PR traceability gate template
+- `templates/docs/SRS/REQ-template.md`: REQ starter template
+- `templates/docs/SRS/TRACEABILITY-template.md`: traceability matrix starter template
+- `bootstrap/install.sh`: copy base assets into a target project
+
+### Pre-flight Scope Decision (Step 0)
+새 기능이나 변경 요청이 들어오면, requirement drafting을 시작하기 **전에** 먼저 아래 명령으로 SRS 대상 여부를 판정한다.
+
+| Asset | 용도 |
+|---|---|
+| `base/.github/prompts/decide-requirement-scope.prompt.md` | 변경 요청을 입력받아 4종 판정 결과 반환 |
+| `base/.github/instructions/requirement-scope-decision.instructions.md` | 판정 기준 및 출력 형식 가이드 |
+| `base/.github/prompts/reopen-requirement-status.prompt.md` | `Approved/Implemented/Deprecated` requirement를 `Proposed`(또는 `Re-review`)로 되돌리기 위한 결정/충돌 검토 |
+| `base/.github/instructions/reopen-requirement-discovery.instructions.md` | REQ 미지정 입력 시 후보 탐색(키워드/점수/동점 처리) 커스터마이징 가이드 |
+
+**판정 결과 4종**
+1. `New SRS requirement needed` — 새 REQ 문서 작성
+2. `Update existing SRS requirement` — 기존 REQ 문서 수정
+3. `Technical spec only` — SRS 변경 없이 technical spec만 업데이트
+4. `Needs owner decision` — 운영 리스크/책임이 불명확하여 소유자 결정 필요
+
+## Install into a project
+
+```bash
+bash .vendor/myagent-kit/bootstrap/install.sh /path/to/project
+```
+
+변경 적용 없이 계획만 확인하려면 dry-run을 사용한다.
+
+```bash
+bash .vendor/myagent-kit/bootstrap/install.sh /path/to/project --dry-run
+```
+
+옵션: 기존 `.github/copilot-instructions.md`를 덮어쓰지 않고 병합하려면 opt-in 플래그를 사용한다.
+
+```bash
+bash .vendor/myagent-kit/bootstrap/install.sh /path/to/project --merge-copilot-instructions
+```
+
+병합 정책 요약:
+- marker 이름은 `myagent-kit`로 고정된다.
+- 기존 파일이 있으면 `.github/copilot-instructions.md.bak`으로 최근 1개 백업 후 병합한다.
+- 병합은 `myagent-kit` 관리 섹션만 갱신하고 `project-specific` 섹션은 유지한다.
+- marker 쌍이 손상된 경우 병합을 중단하고 백업본으로 롤백한다.
+
+In subtree-based usage:
+
+```bash
+git subtree add --prefix=.vendor/myagent-kit https://github.com/<owner>/myagent-kit.git main --squash
+bash .vendor/myagent-kit/bootstrap/install.sh .
+bash .vendor/myagent-kit/bootstrap/install.sh . --dry-run
+bash .vendor/myagent-kit/bootstrap/install.sh . --merge-copilot-instructions
+bash .vendor/myagent-kit/bootstrap/install.sh . --merge-copilot-instructions --dry-run
+```
+
+## 운영 규칙
+
+- SRS는 계약 문서, 구현 문서는 실행 기록으로 분리합니다.
+- 모든 요구사항에 고유 ID를 부여합니다. 예: REQ-001
+- 구현/테스트/릴리즈까지 같은 ID를 계속 사용합니다.
+- 상태 기반으로 관리합니다: Draft → Approved → Implemented → Verified → Released
+
+## 추적/운영 표준
+
+### 1) 식별자 규칙
+- Requirement ID는 `REQ-XXX` 형식을 사용합니다. 예: `REQ-001`
+- Acceptance Criteria는 requirement 내부에서 `AC1`, `AC2`처럼 번호를 고정합니다.
+- 이슈/PR 제목에는 requirement ID를 포함합니다. 예: `[REQ-001] ...`
+
+### 2) 증거(Evidence) 연결 규칙
+- 구현 이슈에는 `Acceptance Criteria Mapping`을 작성합니다. (`ACx -> Task`)
+- PR에는 어떤 AC가 어떤 변경으로 충족되었는지 명시합니다.
+- 테스트 이름 또는 테스트 설명에도 requirement ID를 포함합니다.
+- 릴리즈 노트에는 포함된 requirement ID 목록을 남깁니다.
+
+### 3) 추적 문서 운영
+- 추적 매트릭스는 `docs/SRS/traceability-matrix.md`로 운영합니다.
+- 초기 작성은 `templates/docs/SRS/TRACEABILITY-template.md`를 복사해 사용합니다.
+- 매트릭스의 각 행은 최소한 `REQ ID`, `AC`, `Issue/PR`, `Test`, `Status`를 채웁니다.
+
+### 4) 최소 운영 절차
+1. Requirement 작성 및 ID 확정
+2. Requirement를 `Approved`로 전환
+3. Implementation Issue 생성 (AC 매핑 포함)
+4. PR 생성 (REQ/AC 충족 근거 기입)
+5. 테스트 증거 업데이트
+6. Requirement 상태를 `Implemented`/`Verified`로 전환
+7. 릴리즈 시 매트릭스와 릴리즈 노트에 REQ ID 반영
+
+## myagent-kit Development Life Cycle
+
+### Phase 0. Workspace Bootstrap
+- 프로젝트에 myagent-kit 자산을 설치한다.
+- `bootstrap/install.sh`를 실행해 `.github` 워크플로 자산을 동기화한다.
+
+### Phase 0.5. Pre-flight Scope Decision *(새 기능/변경 요청 진입 시 필수)*
+- `decide-requirement-scope.prompt.md`로 변경 요청이 SRS 대상인지 먼저 판정한다.
+- 판정 결과에 따라 다음 단계를 결정한다.
+  - `New SRS requirement needed` → Phase 1로 진행
+  - `Update existing SRS requirement` → 해당 REQ 파일을 수정하고 Phase 2로 진행
+  - `Technical spec only` → SRS 변경 없이 technical spec / implementation note만 업데이트
+  - `Needs owner decision` → 소유자와 협의 후 위 3가지 중 하나로 재판정
+
+### Phase 1. Requirement Drafting
+- `templates/docs/SRS/REQ-template.md`로 REQ 문서를 작성한다.
+- REQ ID(`REQ-XXX`)를 확정하고, `Acceptance Criteria`를 test 가능한 문장으로 작성한다.
+
+### Phase 2. Requirement Quality Gate
+- `validate-requirement.prompt.md`로 requirement 품질 검토를 수행한다.
+- 모호성, 누락 필드, impacted area, change log 누락을 수정한다.
+
+### Phase 3. Requirement Approval Gate
+- `approve-requirement.prompt.md`로 `Proposed -> Approved` 전환 가능 여부를 확인한다.
+- 승인 이력(Change Log)을 남기고 상태를 `Approved`로 변경한다.
+
+### Phase 3.5. Requirement Reopen / Re-review
+- 구현 전/후에 계약 변경, acceptance criteria 재정의, 리스크 재평가가 필요하면 `reopen-requirement-status.prompt.md`를 사용한다.
+- 입력 예시: `REQ-003, REQ-011; API 응답 필드 계약을 다시 정리해야 해서 재검토 필요`.
+- 결과에서 사용자 결정 항목(목표 상태: `Proposed` vs `Re-review`)과 충돌 후보 REQ를 먼저 확인한 뒤 REQ 문서/인덱스를 수정한다.
+
+### Phase 4. Pre-Implementation Design Review
+- Implementation Issue를 생성하고 설계검토 체크리스트를 작성한다.
+- 아키텍처, 인터페이스, 데이터, 오류 처리, 보안/성능, 테스트 전략을 합의한다.
+- 미해결 항목은 `Open Items / Assumptions`에 기록한다.
+
+### Phase 5. Implementation Planning
+- `create-implementation-issue.prompt.md`로 구현 이슈를 생성한다.
+- `Acceptance Criteria Mapping`으로 AC와 작업 항목을 연결한다.
+- AI Agent 작업과 Human 작업을 분리한다.
+
+### Phase 6. Implementation & PR
+- 구현을 진행하고 PR을 생성한다.
+- `.github/pull_request_template.md`로 REQ ID, AC 커버리지, 테스트 증거를 기록한다.
+
+### Phase 7. Verification & Status Transition
+- 자동/수동 검증 결과를 반영한다.
+- `mark-requirement-implemented.prompt.md`로 `Approved -> Implemented` 전환 가능 여부를 점검한다.
+- 충족 여부가 확인되면 requirement 상태를 전환한다.
+
+### Phase 8. Traceability & Release
+- `docs/SRS/traceability-matrix.md`를 갱신한다.
+- 릴리즈 노트에 반영된 REQ ID를 기록한다.
+- 필요 시 운영 문서/회고 문서에 residual risk를 남긴다.
@@ -0,0 +1,72 @@
+---
+name: "Implementation From Approved Requirement"
+about: "Create an implementation issue from an Approved SRS requirement"
+title: "[REQ-XXX] Implement <short title>"
+labels: ["implementation", "requirement"]
+assignees: []
+---
+
+<!-- 기본 작성 언어는 한국어로 유지하고, 중요한 technical term는 영어 원문을 유지하거나 괄호로 병기한다. -->
+
+## 배경 (Context)
+- Requirement ID:
+- Requirement Link:
+- Status Check: Approved
+
+## 범위 (Scope)
+- In Scope:
+- Out of Scope:
+
+## 구현 전 설계검토 체크리스트 (Pre-Implementation Design Review)
+- [ ] Architecture approach is documented and agreed
+- [ ] Public interface/API contract changes are identified
+- [ ] Data model/schema impact is reviewed
+- [ ] Error handling and fallback strategy is defined
+- [ ] Security/privacy impact is reviewed
+- [ ] Performance/scalability impact is reviewed
+- [ ] Test strategy (unit/integration/e2e/manual) is defined
+- [ ] Rollback or feature-flag strategy is defined when needed
+- [ ] Unknowns, assumptions, and decision owners are recorded
+- [ ] Human review sign-off completed (or `No additional design review required.`)
+
+### 설계 결정 요약 (Design Decisions)
+- Decision 1:
+- Decision 2:
+
+### 미해결 항목 / 가정 (Open Items / Assumptions)
+-
+
+## AI Agent 작업 (AI Agent Work)
+- [ ] Code change task 1
+- [ ] Code change task 2
+- [ ] Automated validation task
+
+## 사람 작업 (Human Work)
+- [ ] Approve scope or open questions
+- [ ] Perform required manual verification
+
+## Acceptance Criteria Mapping
+- REQ AC1 -> Task(s):
+- REQ AC2 -> Task(s):
+
+## AI 검증 요약 (AI Validation Summary)
+- Automated tests/checks to run:
+- Expected evidence:
+
+## 사람 확인 체크리스트 (Human Verification Checklist)
+- [ ] Verify:
+- [ ] Confirm:
+- If no human verification is required, write: `No manual verification required.`
+
+## 열린 질문 (Open Questions)
+-
+
+## 리스크 (Risks)
+-
+
+## 완료 조건 (Definition of Done)
+- [ ] All mapped acceptance criteria are satisfied
+- [ ] Tests are added or updated
+- [ ] AI-completable work is finished and evidence is attached
+- [ ] Human-only work is completed or explicitly marked not required
+- [ ] Docs or change notes are updated if needed
@@ -0,0 +1,16 @@
+# myagent-kit Managed Copilot Instructions
+
+아래 규칙은 myagent-kit가 관리하는 기본 게이트다.
+
+## SRS-first Code Change Gate
+- 소스 코드 변경이 필요한 요청이면 먼저 `docs/SRS/index.md`와 관련 REQ/SRS 문서를 확인한다.
+- SRS와 기술 문서(`docs/technical/`) 기준과 코드 변경 방향이 충돌하면 즉시 사용자에게 선택을 요청한다.
+- 사용자가 SRS 변경을 선택하면 `/reopen-requirement-status` 절차를 먼저 수행한다.
+- 사용자가 코드 변경 지속을 선택하면 해당 결정을 명시적으로 기록한 뒤 진행한다.
+
+## No-Conflict Path
+- 충돌이 없으면 기술 문서 업데이트가 필요한지 먼저 확인하고, 필요 시 기술 문서를 선반영한 뒤 소스 수정을 진행한다.
+
+## Traceability
+- 코드 변경 시 관련 REQ ID를 확인하고, 가능하면 PR/이슈/테스트 증거와 연결한다.
+- 판단이 불충분하면 가정하지 말고 사용자에게 필요한 결정을 질문한다.
@@ -0,0 +1,50 @@
+---
+description: "Use when customizing REQ candidate discovery rules for /reopen-requirement-status command, including keyword dictionary, scoring, tie-breaks, and normalization policy."
+applyTo: ".github/prompts/reopen-requirement-status.prompt.md"
+---
+# Reopen Requirement Discovery Guidelines
+
+## 목적
+`/reopen-requirement-status` 입력에 REQ ID가 없을 때, 관련 REQ 후보를 일관된 기준으로 탐색하고 우선순위를 정한다.
+
+## 후보 탐색 우선순위
+1. 계약 키워드 일치
+- `API`, `endpoint`, `request`, `response`, `schema`, `field`, `CLI`, `command`, `option`, `UI`, `event`, `config`, `env`, `deploy`, `integration`
+2. 영향 영역 일치
+- 입력의 변경 대상 모듈/문서/테스트와 REQ의 `Impacted Area` 교집합
+3. 목적/행동 일치
+- 입력의 동사/의도(추가, 제거, 변경, 완화, 강화, 비활성화 등)와 REQ `Intent`/`Requirement`의 의미 유사도
+4. 상태 가중치
+- 현재 상태가 `Approved`, `Implemented`, `Deprecated`인 REQ 우선
+
+## 점수 및 신뢰도
+- 점수식: `키워드(0-5) + 영향영역(0-3) + 의미유사(0-2) + 상태가중치(0-1)`
+- 정렬: 총점 내림차순
+- 신뢰도:
+  - `High(7-11)`
+  - `Medium(4-6)`
+  - `Low(0-3)`
+
+## 도메인 키워드 사전 (커스터마이즈 가능)
+- Auth & Access: `auth`, `login`, `oauth`, `token`, `permission`, `rbac`, `role`, `scope`
+- Billing & Subscription: `billing`, `invoice`, `payment`, `subscription`, `plan`, `quota`, `credit`
+- Data & Migration: `schema`, `migration`, `backfill`, `etl`, `import`, `export`, `retention`
+- API & Contract: `api`, `endpoint`, `request`, `response`, `versioning`, `webhook`, `payload`
+- Runtime & Operations: `deploy`, `rollback`, `release`, `monitoring`, `alert`, `slo`, `incident`
+- Configuration: `config`, `env`, `feature flag`, `toggle`, `secret`, `parameter`
+- UX & Interface: `ui`, `ux`, `screen`, `form`, `flow`, `command`, `cli`, `option`
+- Testing & Quality: `test`, `e2e`, `regression`, `coverage`, `validation`, `acceptance`
+
+## 정규화 규칙
+- 사전에 없는 표현이 입력에 등장하면 의미가 유사한 사전 키워드로 1회 정규화해 근거에 표기한다.
+- 예: `권한` -> `permission`, `과금` -> `billing`
+
+## 동점 처리
+- 동일 점수 후보가 여러 개면 최신 Change Log 항목이 있는 REQ를 우선한다.
+- 여전히 동점이면 현재 active 상태(`Approved`/`Implemented`) REQ를 우선한다.
+- 추가 동점이면 REQ ID가 작은 항목을 우선한다.
+
+## 출력 권장
+- 후보는 최대 5개 제시
+- 각 후보에 `REQ ID`, `신뢰도`, `점수`, `근거 키워드`, `영향 영역`을 포함
+- 확정 전에는 `Immediate Questions`로 최종 대상 REQ 선택을 먼저 요청
@@ -0,0 +1,52 @@
+---
+description: "Use when evaluating whether a new feature or change request requires a new or updated SRS requirement, a technical spec update only, or needs owner decision. Apply before starting requirement drafting."
+applyTo: "docs/SRS/**/*.md"
+---
+# Requirement Scope Decision Guidelines
+
+## 목적
+새 기능 요청이나 변경 사항이 들어왔을 때, SRS에 등록해야 하는지(신규 또는 기존 REQ 수정) 아니면 technical spec / implementation note만 업데이트하면 되는지를 먼저 판정한다.
+이 판정을 거침으로써 불필요한 REQ 생성을 방지하고, SRS에 등록돼야 할 변경이 누락되는 것을 예방한다.
+
+## 판정 결과 분류 (4종)
+1. **New SRS requirement needed** — 새 REQ 문서를 작성해야 한다.
+2. **Update existing SRS requirement** — 기존 REQ 문서를 수정해야 한다.
+3. **Technical spec only** — SRS 변경 없이 technical spec / implementation note만 업데이트한다.
+4. **Needs owner decision** — 운영 리스크나 승인 기준이 불명확하여 소유자(Owner) 결정이 필요하다.
+
+## SRS 대상 판정 기준 (다음 중 하나라도 해당하면 SRS)
+
+### 외부 계약 변화
+- 사용자 또는 외부 시스템이 관찰하는 계약이 바뀌는 경우
+- API / CLI / UI / Event / Data schema / Config / Deployment / Integration 요구사항이 변경되는 경우
+
+### 측정 가능한 Non-Functional 변경
+- 성능, 보안, 가용성, 확장성 등 측정 기준이 추가되거나 변경되는 경우
+
+### Acceptance Criteria 및 승인 게이트 필요
+- 변경 사항에 대해 명시적 수락 기준과 승인 이력이 필요한 경우
+
+## Technical Spec Only 판정 기준 (다음에 해당하면 SRS 불필요)
+- 내부 리팩터링 (외부 계약 변화 없음)
+- 라이브러리 교체 (동일한 외부 인터페이스 유지)
+- 코드 구조 / 패턴 변경 (기능 동작 동일)
+- 외부 계약을 바꾸지 않는 구현 최적화
+
+## Borderline / Needs Owner Decision 판정 기준
+- 운영 리스크나 승인 책임이 불명확한 경우
+- 제품 의도가 불분명하거나 범위가 애매한 경우
+- 위 기준만으로 분류가 확정되지 않는 경우
+
+## New vs. Update 구분 기준
+- 동일 기능/계약 범위의 변경 → `Update existing SRS requirement`
+- 새 기능/계약/인터페이스의 추가 → `New SRS requirement needed`
+- 기존 REQ 검색 시 `docs/SRS/index.md`의 Requirement Register를 먼저 확인한다.
+
+## 판정 출력 형식
+판정 결과는 항상 다음 항목을 포함해야 한다.
+1. **Decision** — 위 4종 중 하나
+2. **Why** — 판정 근거 (구체적으로 어떤 기준에 해당하는지)
+3. **Recommended Type** — SRS 대상인 경우, 해당 requirement type (Interface / Data / Deployment 등)
+4. **Existing REQ candidates** — Update 가능성이 있는 기존 REQ ID 목록 (해당 시)
+5. **Next Action** — 판정 결과에 따른 다음 단계 안내
+6. **Open Questions** — 추가 확인이 필요한 사항 (없으면 `없음`)
@@ -0,0 +1,53 @@
+---
+description: "Use when writing or editing SRS documents, requirement files, acceptance criteria, change logs, or impacted area entries under docs/SRS. Ensures requirement quality, traceability, and testable wording."
+applyTo: "docs/SRS/**/*.md"
+---
+# SRS Document Guidelines
+
+## Requirement 타입 분류
+
+### 분류 의사결정 규칙 (우선순위 순)
+1. **Installation**: "시스템 설치, 환경 구성, 초기화 절차를 정의하는가?" → YES면 Installation
+   - 예: Docker 이미지 빌드, 데이터베이스 마이그레이션, 사전 조건 설정
+2. **Interface**: "사용자가 직접 조작하거나 실행하는 방식을 정의하는가?" → YES면 Interface
+   - 예: CLI 명령어, API 엔드포인트, 웹 UI 기능, 제어 방식
+3. **Configuration**: "시스템 또는 기능의 설정 옵션, 커스터마이징을 정의하는가?" → YES면 Configuration
+   - 예: 설정 파라미터, 옵션 항목, 환경 변수, 커스터마이징 포인트
+4. **Data**: "데이터 저장, 로드, 구조, 파일 형식, 스키마를 정의하는가?" → YES면 Data
+   - 예: 설정 파일 형식, 데이터베이스 스키마, API 요청/응답 구조
+5. **Exception & Error Handling**: "오류 처리, 예외 복구, 재시도 전략을 중심으로 하는가?" → YES면 Exception & Error Handling
+   - 예: 네트워크 오류 재시도, 데이터 검증 실패 처리, 복구 절차
+6. **Deployment**: "배포 방식, 운영 절차, 배포 환경을 정의하는가?" → YES면 Deployment
+   - 예: 컨테이너 배포, 스택 관리, 운영 가이드
+7. **Documentation**: "문서 작성, 가이드, 매뉴얼, 안내서를 정의하는가?" → YES면 Documentation
+   - 예: 사용자 가이드, API 문서, 운영 매뉴얼, 튜토리얼
+8. **Integration**: "외부 시스템 연동, 플러그인, 확장 기능을 정의하는가?" → YES면 Integration
+   - 예: 3rd party 서비스 연동, 플러그인 인터페이스, 확장 메커니즘
+9. **Migration**: "데이터 이전, 버전 업그레이드, 마이그레이션을 정의하는가?" → YES면 Migration
+   - 예: 데이터 마이그레이션, 버전 호환성, 업그레이드 절차
+10. **Testing**: "테스트 전략, QA 요구사항, 검증 방식을 정의하는가?" → YES면 Testing
+    - 예: 테스트 커버리지, 회귀 테스트, 수락 테스트 기준
+11. **Non-Functional**: 위 모든 경우에 해당하지 않으면 → Non-Functional
+    - 예: 성능 목표, 보안 정책, 확장성, 호환성, 신뢰성 요구사항
+
+**주의**: requirement가 여러 분류에 해당하면 주된 제약 또는 목적에 따라 하나로만 선택한다. 예를 들어:
+- "Docker Compose로 배포할 수 있어야 한다" → Deployment
+- "배포 시 환경 변수로 설정 가능해야 한다" → Configuration
+- "배포 전에 다음 점검 항목을 검증해야 한다" → Testing/Documentation
+
+- `docs/SRS/index.md`는 SRS 운영 기준과 Requirement Register를 관리하는 문서로 유지한다.
+- `docs/SRS/REQ-XXX_*.md`는 하나의 requirement만 다루고, 다른 requirement 내용을 섞지 않는다. 파일은 Type별 폴더에 저장한다. 예: `docs/SRS/Deployment/REQ-001_docker-compose-release.md`
+- 새 requirement 번호의 source of truth는 `docs/SRS/index.md`의 `Next Requirement ID`다.
+- requirement 본문에는 최소한 `Status`, `Type`, `Priority`, `Owner`, `Intent`, `Requirement`, `Acceptance Criteria`, `Impacted Area`, `Change Log`가 포함되어야 한다.
+- `Acceptance Criteria`는 관찰 가능하고 test 가능한 문장으로 작성한다.
+- 모호한 표현("개선한다", "적절히 처리한다", "최적화한다")은 측정 기준 없이 사용하지 않는다.
+- requirement를 수정하면 해당 REQ 파일의 `Change Log`도 함께 갱신한다.
+- `Impacted Area`는 `Docs`, `Modules`, `Tests`를 모두 검토한 뒤 작성한다. 해당 항목이 없으면 `없음`으로 명시한다.
+- implementation issue/PR를 생성하거나 병합할 때는 `docs/SRS/traceability-matrix.md`에서 해당 REQ 행의 `Issue/PR`, `Tests`, `Status`를 갱신한다.
+- 새로운 Type으로 requirement를 추가할 때는 `docs/SRS/<Type>/` 폴더 하위에 저장한다. 아직 없는 Type 폴더면 생성한다.
+- 새로운 requirement를 추가하면 `docs/SRS/index.md`의 Requirement Register에도 같은 ID를 추가한다.
+- 새로운 requirement를 추가하거나 Register가 바뀌면 `docs/SRS/index.md`의 `Next Requirement ID`도 함께 갱신한다.
+- `docs/SRS/index.md`의 `Recent Change Log Summary`는 최신 5건만 유지하고 최신 항목을 위에 둔다.
+- requirement ID와 파일명 prefix는 일치해야 한다. 예: `REQ-002`는 `docs/SRS/<Type>/REQ-002_<slug>.md`.
+- requirement 상태를 `Approved` 또는 `Implemented`로 바꿀 때는 acceptance criteria와 change history가 누락되지 않았는지 먼저 검토한다.
+- requirement 상태를 전환할 때는 `docs/SRS/index.md`의 `Status Transition Evidence` 기준을 따른다.
@@ -0,0 +1,26 @@
+---
+description: "Use when: decide whether a Proposed requirement is ready to move to Approved and generate the required status-change edits"
+name: "Approve Requirement"
+argument-hint: "Paste a Proposed REQ file or select requirement text"
+agent: "agent"
+model: "GPT-5 (copilot)"
+---
+다음 requirement 문서가 `Proposed`에서 `Approved`로 전환 가능한지 검토한다.
+
+입력:
+${input}
+
+검토 규칙:
+- 기준 문서는 [SRS index](../../docs/SRS/index.md) 의 `Status Transition Evidence`와 해당 requirement 문서 구조다.
+- `Status`, `Type`, `Priority`, `Owner`, `Intent`, `Requirement`, `Acceptance Criteria`, `Impacted Area`, `Change Log` 존재 여부를 검토한다.
+- Type이 SRS index의 분류 도표에 정의된 타입 중 정확하게 하나로 지정되었는지 확인한다.
+- `Acceptance Criteria`가 구현 기준으로 충분히 구체적인지 판단한다.
+- 중요한 assumption 또는 open question이 남아 있으면 승인 blocker로 본다.
+- 승인 가능하면 status 변경과 Change Log 추가 초안을 함께 제안한다.
+- 승인 불가하면 blocker를 우선순위 순으로 정리한다.
+
+출력 형식:
+1. Approval Decision: `Approved-ready` 또는 `Not ready`
+2. Blockers
+3. Suggested Edits
+4. Approval Change Log Draft
@@ -0,0 +1,32 @@
+---
+description: "Use when: complete a partial SRS requirement draft into a full REQ file with acceptance criteria and impacted area"
+name: "Complete Requirement Draft"
+argument-hint: "Paste a partial requirement draft or describe the feature"
+agent: "agent"
+model: "GPT-5 (copilot)"
+---
+다음 입력을 기반으로 SRS requirement 초안을 완성한다.
+
+입력:
+${input}
+
+작업 규칙:
+- SRS 기준 문서는 [SRS index](../../docs/SRS/index.md) 와 관련 [REQ template](../../docs/SRS/REQ-template.md) 를 따른다.
+- 입력에 `REQ-XXX` 형식의 명시적 ID가 없으면, [SRS index](../../docs/SRS/index.md)의 `Next Requirement ID`를 우선 읽어 그 값을 사용한다. `Next Requirement ID`가 없거나 신뢰할 수 없으면 `Requirement Register`와 기존 REQ 파일들 기준의 최고 번호에 1을 더한 값을 사용한다.
+- 사용자가 이미 특정 REQ ID를 명시했으면 그 ID를 유지하고 임의로 바꾸지 않는다.
+- requirement의 유형을 인식하고 `Type` 필드를 정확하게 지정한다. 분류는 [SRS index](../../docs/SRS/index.md)의 "Requirement 작성 규칙" 또는 [SRS instructions](../../.github/instructions/srs.instructions.md)의 "분류 의사결정 규칙"을 따른다.
+- 최종 `Type`과 `REQ ID`를 이용해 추천 파일 경로를 함께 제시한다. 형식은 `docs/SRS/<Type>/REQ-XXX_<slug>.md`를 사용한다.
+- `<slug>`는 requirement 제목을 기반으로 소문자 kebab-case 영문으로 생성한다. 공백은 `-`로 치환하고, 영문/숫자/`-`만 남긴다.
+- 제목이 한글이거나 slug 생성이 불명확하면 의미를 유지하는 짧은 영문 slug를 보수적으로 제안한다.
+- 사용자가 제공한 의도와 핵심 동작을 보존한다.
+- 빠진 항목은 보수적으로 보완하되, 추정이 필요한 내용은 `Notes`에 assumption으로 분리한다.
+- `Acceptance Criteria`는 반드시 test 가능하게 작성한다.
+- `Impacted Area`는 Docs, Modules, Tests로 구분한다.
+- 새로 할당한 ID를 문서 제목 `# REQ-XXX: ...`에 반영한다.
+- 결과는 REQ 파일에 바로 붙여넣을 수 있는 Markdown 형식으로만 출력한다.
+- 코드 구현 계획은 포함하지 않는다.
+
+출력 형식:
+1. `Recommended File Path: docs/SRS/<Type>/REQ-XXX_<slug>.md` 한 줄
+2. 실제 할당된 ID가 반영된 `# REQ-XXX: ...` 형식의 전체 문서 본문
+3. `## Change Log` 아래에 초안 생성용 `CHG-YYYYMMDD-01` 항목 1개 포함
@@ -0,0 +1,42 @@
+---
+description: "Use when: create an implementation plan and GitHub issue draft from an Approved requirement"
+name: "Create Implementation Issue"
+argument-hint: "Paste an Approved REQ file"
+agent: "agent"
+model: "GPT-5 (copilot)"
+---
+다음 `Approved` requirement 문서를 기반으로 implementation issue 초안을 생성한다.
+
+입력:
+${input}
+
+작업 규칙:
+- 기준 문서는 [SRS index](../../docs/SRS/index.md) 와 해당 REQ 문서다.
+- 출력 언어는 기본적으로 한국어로 작성한다.
+- section 제목, 설명, 작업 지시문은 한국어를 우선 사용하되, 중요한 technical term는 영어를 유지하거나 한국어 뒤 괄호로 병기한다. 예: `AI Agent Work`, `Human Verification Checklist`, `Acceptance Criteria`, `Open Questions`, `Risk`, `Definition of Done`.
+- 코드 식별자, 파일 경로, 명령어, API 이름, 테스트 이름, UI 라벨 등 구현 대상과 직접 연결되는 literal은 영어 원문을 유지한다.
+- requirement의 `Acceptance Criteria`를 구현 task로 분해한다.
+- task는 구현 단위로 나누고, 각 task를 `AI Agent가 완료 가능한 작업`과 `Human이 수행해야 하는 작업`으로 구분한다.
+- test task를 반드시 포함한다.
+- 각 acceptance criteria 또는 task에 대해 다음을 판단한다:
+	- AI Agent가 코드 변경과 자동 검증까지 완료할 수 있는가
+	- Human이 직접 확인해야 하는 수동 검증이 남는가
+- Human이 직접 확인해야 하는 항목이 있으면 `Human Verification Checklist`에 구체적인 확인 절차와 기대 결과를 작성한다.
+- AI Agent가 자체적으로 테스트를 완료할 수 있어 Human 확인이 불필요하면 `Human Verification Checklist`에 `No manual verification required.`를 명시하고 그 근거를 `AI Validation Summary`에 적는다.
+- `Impacted Area`를 기반으로 module/docs/test 변경 범위를 제시한다.
+- 미해결 가정이나 리스크가 있으면 issue 본문에 `Open Questions`와 `Risks`로 명시한다.
+- 출력은 GitHub issue에 바로 붙여 넣을 수 있는 Markdown 형식으로만 작성한다.
+
+출력 형식:
+1. Issue Title
+2. 배경 (Context)
+3. 범위 (Scope)
+4. AI Agent 작업 (AI Agent Work) 체크리스트
+5. 사람 작업 (Human Work) 체크리스트
+6. Acceptance Criteria Mapping (REQ 기준)
+7. AI 검증 요약 (AI Validation Summary)
+8. 사람 확인 체크리스트 (Human Verification Checklist)
+9. 열린 질문 (Open Questions)
+10. 리스크 (Risks)
+11. 완료 조건 (Definition of Done)
+12. GitHub Issue Create Command (`gh issue create`) 예시
@@ -0,0 +1,38 @@
+---
+description: "Use when: evaluate whether a new feature or change request needs a new SRS requirement, an update to an existing one, a technical spec update only, or owner decision — before starting requirement drafting"
+name: "Decide Requirement Scope"
+argument-hint: "Describe the feature or change request: include feature description, issue body, and/or PR/diff summary"
+agent: "agent"
+model: "GPT-5 (copilot)"
+---
+다음 입력을 기반으로, 이 변경이 SRS 대상인지 아닌지를 판정한다.
+
+입력:
+${input}
+
+판정 규칙:
+- 기준 문서는 [requirement-scope-decision instructions](../../.github/instructions/requirement-scope-decision.instructions.md) 와 [SRS index](../../docs/SRS/index.md) 의 Requirement Register다.
+- 다음 4가지 결과 중 하나를 반드시 반환한다.
+  1. `New SRS requirement needed`
+  2. `Update existing SRS requirement`
+  3. `Technical spec only`
+  4. `Needs owner decision`
+- 판정 기준을 순서대로 적용한다.
+  - 사용자/외부 시스템이 관찰하는 계약(API, CLI, UI, Event, Data schema, Config, Deployment, Integration)이 바뀌는가? → YES면 SRS
+  - 측정 가능한 Non-Functional requirement(성능, 보안, 가용성 등)가 추가/변경되는가? → YES면 SRS
+  - Acceptance Criteria 및 명시적 승인 게이트가 필요한가? → YES면 SRS
+  - 위 기준에 모두 해당하지 않으면서 내부 리팩터링·라이브러리 교체·코드 구조 변경·구현 최적화인가? → Technical spec only
+  - 위 기준만으로 분류가 확정되지 않거나 운영 책임/리스크가 불명확한가? → Needs owner decision
+- SRS 대상으로 판정되면, 신규 기능/계약인지 기존 REQ 범위 내 변경인지를 구분한다.
+  - 기존 REQ에 해당하는 경우 [SRS index](../../docs/SRS/index.md) 의 Requirement Register에서 후보 REQ ID를 찾아 제시한다.
+- Technical spec only로 판정되면, 불필요한 REQ 생성을 명시적으로 피하도록 안내한다.
+- 결과에는 항상 `Why`와 `Next Action`을 포함한다.
+- `Open Questions`가 없으면 `없음`으로 명시한다.
+
+출력 형식:
+1. **Decision**: `New SRS requirement needed` / `Update existing SRS requirement` / `Technical spec only` / `Needs owner decision` 중 하나
+2. **Why**: 판정 근거 — 어떤 기준에 해당하는지 구체적으로 설명
+3. **Recommended Type**: (SRS 대상인 경우만) Interface / Data / Deployment / Configuration 등 해당 requirement type
+4. **Existing REQ candidates**: (Update 가능성이 있는 경우만) 관련 REQ ID와 제목 목록. 해당 없으면 생략
+5. **Next Action**: 판정 결과에 따른 다음 단계 안내
+6. **Open Questions**: 추가 확인이 필요한 사항. 없으면 `없음`
@@ -0,0 +1,25 @@
+---
+description: "Use when: decide whether an Approved requirement is ready to move to Implemented and generate the required status-change edits"
+name: "Mark Requirement Implemented"
+argument-hint: "Paste an Approved REQ file and implementation evidence"
+agent: "agent"
+model: "GPT-5 (copilot)"
+---
+다음 requirement 문서와 implementation evidence를 검토해 `Approved`에서 `Implemented`로 전환 가능한지 판단한다.
+
+입력:
+${input}
+
+검토 규칙:
+- 기준 문서는 [SRS index](../../docs/SRS/index.md) 의 `Status Transition Evidence`와 해당 requirement 문서 구조다.
+- requirement의 `Acceptance Criteria`가 implementation evidence, tests, 또는 manual verification으로 충족되었는지 확인한다.
+- 충족되지 않은 acceptance criteria가 있으면 구현 완료로 판정하지 않는다.
+- 구현 완료 가능하면 status 변경, 잔여 리스크, Change Log 추가 초안을 함께 제안한다.
+- 구현 완료 불가하면 미충족 기준과 필요한 검증 항목을 정리한다.
+
+출력 형식:
+1. Implementation Decision: `Implemented-ready` 또는 `Not ready`
+2. Unverified Criteria
+3. Suggested Edits
+4. Implementation Change Log Draft
+5. Residual Risk
@@ -0,0 +1,44 @@
+---
+description: "Use when: move Approved, Implemented, or Deprecated requirements back to Proposed (or Re-review) with decision checkpoints, conflict candidates, and fallback REQ discovery"
+name: "Reopen Requirement Status"
+argument-hint: "(선택) REQ-XXX, REQ-XXX; 변경 의도와 범위 설명"
+agent: "agent"
+model: "GPT-5 (copilot)"
+---
+다음 입력을 기준으로 지정된 requirement를 재검토 상태로 되돌리는 변경안을 만든다.
+
+입력:
+${input}
+
+입력 해석 규칙:
+- 입력 형식은 기본적으로 `REQ-XXX, REQ-XXX; 이렇게 이렇게 변경할거야.` 를 따른다.
+- `;` 앞은 대상 REQ ID 목록, 뒤는 변경 의도/배경으로 해석한다.
+- 구분자는 쉼표/공백을 모두 허용하되, 최종적으로 중복 없는 REQ ID 목록으로 정규화한다.
+- 입력에 REQ ID가 없으면 전체 입력을 변경 의도/배경으로 간주한다.
+
+작업 규칙:
+- 기준 문서는 `docs/SRS/index.md`, 해당 REQ 파일, [SRS instructions](../../.github/instructions/srs.instructions.md), [Reopen requirement discovery instructions](../../.github/instructions/reopen-requirement-discovery.instructions.md) 다.
+- 대상 REQ ID가 명시되지 않으면 `docs/SRS/index.md` Requirement Register와 REQ 파일 제목/Intent/Requirement/Impacted Area를 기반으로 관련 후보를 탐색한다.
+- 후보 탐색, 점수화, 신뢰도, 동점 처리, 도메인 키워드 정규화는 [Reopen requirement discovery instructions](../../.github/instructions/reopen-requirement-discovery.instructions.md)를 그대로 따른다.
+- REQ 미지정 시 후보는 최대 5개까지 제시하고, 신뢰도(High/Medium/Low)와 근거(키워드/영향 영역)를 함께 제시한다.
+- REQ 미지정 시 확정 전에는 상태 변경안을 단정하지 말고, `Immediate Questions`에서 최종 대상 REQ 확인 질문을 먼저 제시한다.
+- 사용자가 후보 중 선택하면 선택된 REQ 기준으로 상태 되돌림 변경안을 완성한다.
+- 대상 REQ의 현재 상태가 `Approved`, `Implemented`, `Deprecated` 중 하나인지 확인한다.
+- 상태 되돌림의 목표 상태는 기본 `Proposed`로 제안한다.
+- 팀이 `재검토 상태`를 별도로 운용하면 목표 상태를 `Re-review`(또는 팀 표기)로 제안할 수 있다. 단, 최종 상태값은 사용자 결정 항목으로 분리한다.
+- 각 REQ마다 왜 되돌려야 하는지(계약 변경, acceptance criteria 변경, 리스크 발견, 구현 불일치 등) 근거를 1-2줄로 요약한다.
+- 변경 전/후 영향으로 충돌 가능성이 있는 REQ 후보를 `docs/SRS/index.md` Requirement Register 기준으로 제시한다.
+- 충돌 후보는 다음 기준으로 찾는다: 동일 기능 영역, 동일 인터페이스/API/CLI/데이터 스키마, 같은 모듈/문서 영향 범위, 기존 acceptance criteria 중복/상충.
+- 사용자가 결정해야 할 항목을 별도 섹션으로 분리한다.
+- 결정 누락 시 즉시 물어야 할 질문을 먼저 제시한다.
+- 실제 문서 변경을 수행하는 대신, 바로 적용 가능한 수정안(상태, Change Log, impacted area 재검토 포인트)을 제시한다.
+
+출력 형식:
+1. Reopen Decision
+2. Immediate Questions (없으면 `없음`)
+3. Detected REQ Candidates (REQ 미지정인 경우 필수, 지정된 경우 생략 가능)
+4. User Decisions Required
+5. Suggested Status Changes (REQ별: `from -> to`)
+6. Conflict Candidate REQs (REQ별 후보 ID와 충돌 이유)
+7. Suggested REQ Edits (Status, Intent/Requirement/Acceptance Criteria 영향, Change Log 초안)
+8. Next Action
@@ -0,0 +1,28 @@
+---
+description: "Use when: update docs/SRS/index.md Requirement Register or Recent Change Log Summary after adding or editing REQ files"
+name: "Sync SRS Index"
+argument-hint: "Paste changed REQ files or describe what changed in SRS"
+agent: "agent"
+model: "GPT-5 (copilot)"
+---
+다음 입력을 기준으로 `docs/SRS/index.md`를 갱신하기 위한 제안을 만든다.
+
+입력:
+${input}
+
+작업 규칙:
+- 기준 문서는 [SRS index](../../docs/SRS/index.md) 이다.
+- 새 requirement가 추가되었거나 Register가 바뀌면 `Requirement Register`의 최고 번호를 기준으로 다음 번호를 계산해 `Next Requirement ID`도 함께 갱신한다.
+- 새 requirement가 추가되었으면 `Requirement Register`에 들어갈 행을 만든다.
+- 기존 requirement가 수정되었으면 `Recent Change Log Summary`에 들어갈 요약 항목을 만든다.
+- 기존 구조를 바꾸지 말고, 필요한 행과 요약만 제안한다.
+- `Next Requirement ID`는 `Requirement Register`에 있는 가장 큰 REQ 번호보다 정확히 1 큰 값이어야 한다.
+- `Recent Change Log Summary`는 최신 변경을 위에 두고, 짧은 요약 1줄로 작성한다.
+- `Recent Change Log Summary`는 최신 5건만 유지하도록 제안한다. 5건을 초과하면 제거 또는 대체해야 할 가장 오래된 항목도 함께 설명한다.
+- 출력은 사람이 `docs/SRS/index.md`에 바로 반영할 수 있는 Markdown 조각으로만 작성한다.
+
+출력 형식:
+1. `Next Requirement ID`에 반영할 Markdown bullet
+2. `Requirement Register`에 추가 또는 수정할 Markdown table row
+3. `Recent Change Log Summary`에 추가할 Markdown section
+4. 필요한 경우 only, index에서 제거 또는 갱신해야 할 기존 항목 설명
@@ -0,0 +1,34 @@
+---
+description: "Use when: verify one or more REQ IDs are Approved and create or update the matching docs/technical specifications"
+name: "Sync Technical Specs"
+argument-hint: "Enter REQ IDs, e.g. REQ-011, REQ-007, REQ-012"
+agent: "agent"
+model: "GPT-5 (copilot)"
+---
+다음 입력으로 지정된 requirement ID 목록에 대해, 승인 상태를 확인하고 해당하는 `docs/technical/` 문서를 실제로 갱신한다.
+
+입력:
+${input}
+
+작업 규칙:
+- 입력에서 `REQ-XXX` 목록을 추출한다. 쉼표 또는 공백으로 구분된 여러 ID를 지원한다.
+- 먼저 `docs/SRS/index.md`의 `Requirement Register`와 각 REQ 파일의 `Status`를 함께 확인한다.
+- 두 곳 모두 `Approved`인 requirement만 기술명세 업데이트 대상으로 포함한다.
+- 하나라도 `Approved`가 아니거나 파일을 찾지 못하면 해당 REQ는 blocker로 보고하고, 그 REQ에 대한 technical doc은 수정하지 않는다.
+- `docs/technical/index.md`와 각 technical doc 상단의 `Related REQ`를 기준으로 기존 연결 문서를 찾는다.
+- 연결 문서가 있으면 현재 승인된 requirement에 맞게 내용을 실제로 업데이트한다.
+- 연결 문서가 없으면 `docs/technical/` 아래에 새 문서를 생성하고 `docs/technical/index.md`에 항목을 추가한다.
+- 기술 문서는 SRS를 source of truth로 따르며, 외부 계약이나 acceptance criteria를 재정의하지 않는다. 대신 구현 상세(모듈 책임, 파일 위치, 설정/환경값, 런타임 흐름, validation notes, open implementation points)를 정리한다.
+- 문서 상단에는 반드시 `- Related REQ: ...`를 유지하거나 추가한다.
+- `REQ-011`, `REQ-007`, `REQ-012`는 다음 문서를 우선 후보로 사용한다:
+  - `REQ-011` → `docs/technical/project-structure-baseline.md`
+  - `REQ-007` → `docs/technical/python-runtime-and-packaging.md`
+  - `REQ-012` → `docs/technical/settings-and-env-loading.md`
+- `docs/technical/index.md`의 문서 목록과 연관 REQ 표도 문서 생성/연결 변경 사항에 맞게 함께 갱신한다.
+- 실제 파일 변경을 수행한 뒤, 변경된 파일과 각 REQ의 승인 확인 결과를 요약한다.
+
+출력 형식:
+1. Approval Check
+2. Technical Spec Updates
+3. Files Changed
+4. Remaining Blockers or Notes
@@ -0,0 +1,24 @@
+---
+description: "Use when: review an SRS requirement for ambiguity, missing acceptance criteria, missing impacted area, and change-log gaps"
+name: "Validate Requirement Quality"
+argument-hint: "Paste a REQ file or select requirement text"
+agent: "agent"
+model: "GPT-5 (copilot)"
+---
+다음 requirement 문서를 검토한다.
+
+입력:
+${input}
+
+검토 규칙:
+- 기준은 [SRS index](../../docs/SRS/index.md) 와 관련 requirement 문서 구조를 따른다.
+- 다음 항목을 우선 검토한다: 모호한 표현, test 불가능한 문장, 누락된 acceptance criteria, 누락된 impacted area, 상태/유형/우선순위/owner 누락, Type이 의사결정 규칙에 따라 정확하게 지정되었는지, Change Log 누락 또는 불일치.
+  - Type 분류 규칙: 사용자 조작 방식 → Interface, 데이터 저장/구조 → Data, 오류 처리 → Exception & Error Handling, 그 외 → Non-Functional
+- 중요한 문제부터 우선순위 순으로 정리한다.
+- 문제가 없으면 `No critical findings.` 로 시작한다.
+- requirement 본문을 직접 다시 작성하지 말고, 수정 제안 위주로 답한다.
+
+출력 형식:
+1. Findings
+2. Open Questions
+3. Suggested Edits
@@ -0,0 +1,24 @@
+## Requirement Traceability
+
+- Requirement ID: REQ-XXX
+- Requirement Link: docs/SRS/<Type>/REQ-XXX_<slug>.md
+- Related Issue: #
+
+## Acceptance Criteria Coverage
+- [ ] AC1: <how this PR satisfies it>
+- [ ] AC2: <how this PR satisfies it>
+
+## Test Evidence
+- Automated:
+  - <test command and result summary>
+- Manual:
+  - <verification steps and result>
+  - If not required: `No manual verification required.`
+
+## Impacted Area Check
+- Docs:
+- Modules:
+- Tests:
+
+## Release Notes Input
+- [ ] Added REQ ID to release notes (or tracked release note draft)
@@ -0,0 +1,263 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+KIT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+MERGE_COPILOT_INSTRUCTIONS=0
+DRY_RUN=0
+PROJECT_ROOT=""
+
+usage() {
+    cat <<'EOF'
+Usage: bootstrap/install.sh [PROJECT_ROOT] [--merge-copilot-instructions] [--dry-run]
+
+Options:
+  --merge-copilot-instructions   Opt-in: safely merge .github/copilot-instructions.md
+  --dry-run                      Print planned changes without modifying files
+  -h, --help                     Show this help message
+EOF
+}
+
+log_action() {
+    local message="$1"
+    if [[ "$DRY_RUN" -eq 1 ]]; then
+        echo "[dry-run] $message"
+    else
+        echo "$message"
+    fi
+}
+
+run_or_dry() {
+    if [[ "$DRY_RUN" -eq 1 ]]; then
+        log_action "$*"
+        return 0
+    fi
+    "$@"
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --merge-copilot-instructions)
+            MERGE_COPILOT_INSTRUCTIONS=1
+            shift
+            ;;
+        --dry-run)
+            DRY_RUN=1
+            shift
+            ;;
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        -*)
+            echo "Unknown option: $1" >&2
+            usage >&2
+            exit 1
+            ;;
+        *)
+            if [[ -z "$PROJECT_ROOT" ]]; then
+                PROJECT_ROOT="$1"
+                shift
+            else
+                echo "Unexpected extra argument: $1" >&2
+                usage >&2
+                exit 1
+            fi
+            ;;
+    esac
+done
+
+PROJECT_ROOT="${PROJECT_ROOT:-$(pwd)}"
+
+MANAGED_BEGIN='<!-- BEGIN: myagent-kit (managed - do not edit) -->'
+MANAGED_END='<!-- END: myagent-kit -->'
+PROJECT_BEGIN='<!-- BEGIN: project-specific (safe to edit) -->'
+PROJECT_END='<!-- END: project-specific -->'
+
+count_occurrence() {
+    local needle="$1"
+    local file="$2"
+    grep -cF "$needle" "$file" || true
+}
+
+build_managed_block() {
+    local kit_file="$1"
+    {
+        printf '%s\n' "$MANAGED_BEGIN"
+        cat "$kit_file"
+        printf '\n%s\n' "$MANAGED_END"
+    }
+}
+
+append_project_section_if_missing() {
+    local file="$1"
+    local project_begin_count
+    local project_end_count
+
+    project_begin_count="$(count_occurrence "$PROJECT_BEGIN" "$file")"
+    project_end_count="$(count_occurrence "$PROJECT_END" "$file")"
+
+    if [[ "$project_begin_count" -eq 0 && "$project_end_count" -eq 0 ]]; then
+        cat >> "$file" <<EOF
+
+$PROJECT_BEGIN
+<!-- Add host-project-specific Copilot rules here. -->
+$PROJECT_END
+EOF
+    elif [[ "$project_begin_count" -ne "$project_end_count" ]]; then
+        return 1
+    fi
+}
+
+validate_merged_copilot_file() {
+    local file="$1"
+    local managed_begin_count
+    local managed_end_count
+    local project_begin_count
+    local project_end_count
+
+    managed_begin_count="$(count_occurrence "$MANAGED_BEGIN" "$file")"
+    managed_end_count="$(count_occurrence "$MANAGED_END" "$file")"
+    project_begin_count="$(count_occurrence "$PROJECT_BEGIN" "$file")"
+    project_end_count="$(count_occurrence "$PROJECT_END" "$file")"
+
+    [[ "$managed_begin_count" -eq 1 ]] || return 1
+    [[ "$managed_end_count" -eq 1 ]] || return 1
+    [[ "$project_begin_count" -eq 1 ]] || return 1
+    [[ "$project_end_count" -eq 1 ]] || return 1
+}
+
+merge_copilot_instructions() {
+    local kit_file="$KIT_ROOT/base/.github/copilot-instructions.md"
+    local host_file="$PROJECT_ROOT/.github/copilot-instructions.md"
+    local backup_file="$host_file.bak"
+    local tmp_file
+    local managed_block
+    local managed_begin_count
+    local managed_end_count
+
+    if [[ "$MERGE_COPILOT_INSTRUCTIONS" -ne 1 ]]; then
+        return 0
+    fi
+
+    if [[ ! -f "$kit_file" ]]; then
+        log_action "Skipped Copilot merge: kit template not found at $kit_file"
+        return 0
+    fi
+
+    if [[ "$DRY_RUN" -eq 1 ]]; then
+        if [[ ! -f "$host_file" ]]; then
+            log_action "Would create and initialize $host_file with managed + project-specific sections"
+            return 0
+        fi
+
+        managed_begin_count="$(count_occurrence "$MANAGED_BEGIN" "$host_file")"
+        managed_end_count="$(count_occurrence "$MANAGED_END" "$host_file")"
+
+        log_action "Would back up $host_file to $host_file.bak"
+        if [[ "$managed_begin_count" -eq 1 && "$managed_end_count" -eq 1 ]]; then
+            log_action "Would update managed myagent-kit section in $host_file"
+        elif [[ "$managed_begin_count" -eq 0 && "$managed_end_count" -eq 0 ]]; then
+            log_action "Would append managed myagent-kit section to $host_file"
+        else
+            log_action "Would fail: malformed managed marker pair in $host_file"
+            return 1
+        fi
+
+        local project_begin_count
+        local project_end_count
+        project_begin_count="$(count_occurrence "$PROJECT_BEGIN" "$host_file")"
+        project_end_count="$(count_occurrence "$PROJECT_END" "$host_file")"
+        if [[ "$project_begin_count" -eq 0 && "$project_end_count" -eq 0 ]]; then
+            log_action "Would append project-specific editable section to $host_file"
+        elif [[ "$project_begin_count" -ne "$project_end_count" ]]; then
+            log_action "Would fail: malformed project-specific marker pair in $host_file"
+            return 1
+        fi
+        return 0
+    fi
+
+    managed_block="$(build_managed_block "$kit_file")"
+    tmp_file="$(mktemp)"
+
+    if [[ ! -f "$host_file" ]]; then
+        {
+            printf '%s\n' "$managed_block"
+            printf '\n%s\n' "$PROJECT_BEGIN"
+            printf '<!-- Add host-project-specific Copilot rules here. -->\n'
+            printf '%s\n' "$PROJECT_END"
+        } > "$host_file"
+        validate_merged_copilot_file "$host_file"
+        log_action "Created and initialized $host_file"
+        rm -f "$tmp_file"
+        return 0
+    fi
+
+    cp "$host_file" "$backup_file"
+    managed_begin_count="$(count_occurrence "$MANAGED_BEGIN" "$host_file")"
+    managed_end_count="$(count_occurrence "$MANAGED_END" "$host_file")"
+
+    if [[ "$managed_begin_count" -eq 1 && "$managed_end_count" -eq 1 ]]; then
+        awk \
+            -v begin="$MANAGED_BEGIN" \
+            -v end="$MANAGED_END" \
+            -v block="$managed_block" '
+                BEGIN {
+                    in_block = 0
+                    replaced = 0
+                }
+                $0 == begin {
+                    if (!replaced) {
+                        print block
+                        replaced = 1
+                    }
+                    in_block = 1
+                    next
+                }
+                $0 == end {
+                    in_block = 0
+                    next
+                }
+                !in_block {
+                    print
+                }
+                END {
+                    if (!replaced) {
+                        print ""
+                        print block
+                    }
+                }
+            ' "$host_file" > "$tmp_file"
+    elif [[ "$managed_begin_count" -eq 0 && "$managed_end_count" -eq 0 ]]; then
+        {
+            cat "$host_file"
+            printf '\n%s\n' "$managed_block"
+        } > "$tmp_file"
+    else
+        echo "Malformed managed marker pair in $host_file" >&2
+        cp "$backup_file" "$host_file"
+        rm -f "$tmp_file"
+        return 1
+    fi
+
+    mv "$tmp_file" "$host_file"
+    append_project_section_if_missing "$host_file"
+    validate_merged_copilot_file "$host_file"
+    log_action "Merged $host_file (backup: $backup_file)"
+}
+
+run_or_dry mkdir -p "$PROJECT_ROOT/.github/prompts" \
+                  "$PROJECT_ROOT/.github/instructions" \
+                  "$PROJECT_ROOT/.github/ISSUE_TEMPLATE"
+
+run_or_dry cp "$KIT_ROOT/base/.github/prompts/"*.prompt.md "$PROJECT_ROOT/.github/prompts/"
+run_or_dry cp "$KIT_ROOT/base/.github/instructions/"*.instructions.md "$PROJECT_ROOT/.github/instructions/"
+run_or_dry cp "$KIT_ROOT/base/.github/ISSUE_TEMPLATE/"*.md "$PROJECT_ROOT/.github/ISSUE_TEMPLATE/"
+if [[ -f "$KIT_ROOT/base/.github/pull_request_template.md" ]]; then
+    run_or_dry cp "$KIT_ROOT/base/.github/pull_request_template.md" "$PROJECT_ROOT/.github/pull_request_template.md"
+fi
+
+merge_copilot_instructions
+
+log_action "Installed myagent-kit assets into $PROJECT_ROOT/.github"
@@ -0,0 +1,55 @@
+# REQ-XXX: <요구사항 제목>
+
+- Status: Proposed | Approved | Implemented | Deprecated
+- Type: Interface | Data | Exception & Error Handling | Installation | Configuration | Deployment | Documentation | Integration | Testing | Non-Functional
+- Priority: High | Medium | Low
+- Owner: <담당자 또는 팀>
+
+## Intent
+- <이 요구사항이 필요한 이유와 달성하려는 목표를 1~3문장으로 작성>
+
+## Requirement
+- <시스템이 반드시 수행해야 하는 동작을 단정형 문장으로 작성>
+
+## Acceptance Criteria
+1. Given <선행 조건>, When <행동>, Then <기대 결과>
+2. Given <선행 조건>, When <행동>, Then <기대 결과>
+
+## Impacted Area
+- Docs: <영향 받는 문서 경로>
+- Modules: <영향 받는 모듈/컴포넌트>
+- Tests: <추가/수정해야 하는 테스트>
+
+## Notes
+- <가정, 제약, 미해결 이슈>
+
+## Change Log
+
+### CHG-YYYYMMDD-01
+- Date: YYYY-MM-DD
+- Author: <작성자>
+
+#### Change Summary
+- <무엇이 변경되었는지>
+
+#### Intent
+- <왜 변경했는지>
+
+#### Acceptance Criteria Delta
+- Added:
+  - <추가된 기준>
+- Updated:
+  - <변경된 기준>
+- Removed:
+  - <삭제된 기준>
+
+#### Impacted Area Delta
+- Docs:
+  - <문서 영향>
+- Modules:
+  - <코드 영향>
+- Tests:
+  - <테스트 영향>
+
+#### Validation Plan
+- <검증 방법과 완료 조건>
@@ -0,0 +1,28 @@
+# SRS Traceability Matrix
+
+<!--
+Usage:
+1. Copy this file to docs/SRS/traceability-matrix.md in your target repository.
+2. Keep one row per requirement.
+3. Update Issue/PR, Test Evidence, and Status whenever implementation progresses.
+-->
+
+## Status Definition
+- Planned: Requirement is defined but not yet implemented.
+- In Progress: Implementation issue/PR exists and work is ongoing.
+- Implemented: Code is merged and mapped acceptance criteria are complete.
+- Verified: Required tests and manual checks are completed.
+- Released: Included in a released version.
+
+## Matrix
+
+| REQ ID | AC Mapping | Requirement File | Implementation Issue | PR | Test Evidence | Requirement Status | Delivery Status | Last Updated |
+|---|---|---|---|---|---|---|---|---|
+| REQ-001 | AC1, AC2 | docs/SRS/<Type>/REQ-001_<slug>.md | #123 | #456 | tests/... , CI run link | Approved | Planned | YYYY-MM-DD |
+
+## Update Rules
+- REQ ID must exactly match the SRS requirement file prefix.
+- AC Mapping should reference concrete IDs such as AC1, AC2.
+- Test Evidence should point to executable artifacts: test file path, CI job, or manual verification note.
+- Last Updated uses YYYY-MM-DD.
+- If there is no value yet, use `TBD`.