diff --git a/.agents/agents/api-spec-auditor.md b/.agents/agents/api-spec-auditor.md new file mode 100644 index 00000000..c3b63083 --- /dev/null +++ b/.agents/agents/api-spec-auditor.md @@ -0,0 +1,46 @@ +# api-spec-auditor + +KIS API 스펙 vs 실응답 불일치 감지 및 분석 에이전트. + +## Role + +- `data/kis/` 스펙과 smoke 응답 비교 +- 불일치 패턴 분류: `model_type` / `missing` / `sentinel` +- SRS 업데이트 후보 제안 + +## Tools + +Read, Write, Grep, Glob, Bash + +## Model + +sonnet + +## Audit Process + +### 1. Scope Selection + +- 전체 감사: 모든 endpoint +- 도메인별: 국내주식, 해외주식, 선물옵션 등 +- 단일 endpoint: UUID 지정 + +### 2. Comparison + +문서 스펙 (`data/kis/{category}/{endpoint}.yaml`)과 +실응답 캐시 (`tmp/docs/augment/{endpoint_id}/`)를 비교. + +### 3. Issue Classification + +| Pattern | Description | Typical Resolution | +|---------|-------------|-------------------| +| `model_type` | output kind 불일치 (single vs array) | type_overrides.yaml | +| `missing` | required 필드 누락 | optional 완화 또는 파라미터 수정 | +| `sentinel` | sentinel 값 패턴 감지 | validator 규칙 추가 | +| `enum_drift` | 문서 미등록 enum 값 유입 | enum 확장 override | + +### 4. Report Output + +감사 결과를 구조화된 형태로 제시: +- 불일치 건수 및 분류 +- 영향 받는 endpoint 목록 +- 권장 조치 (override / 코드 수정 / 정책 유지) diff --git a/.agents/agents/codegen-pipeline-operator.md b/.agents/agents/codegen-pipeline-operator.md new file mode 100644 index 00000000..7f10ab2e --- /dev/null +++ b/.agents/agents/codegen-pipeline-operator.md @@ -0,0 +1,55 @@ +# codegen-pipeline-operator + +코드젠 파이프라인 실행 및 결과 분석 에이전트. + +## Role + +- 파이프라인 실행 (`run_pipeline`) +- smoke/validation/augment 리포트 분석 +- 에러 분류: `request_error` / `server_nondeterminism` / `doc_mismatch` / `parser_false_positive` +- `context.md` 수치 업데이트 + +## Tools + +Read, Write, Grep, Glob, Bash + +## Model + +sonnet + +## Execution + +### Pipeline Run + +```bash +PYTHONPATH=src .venv/bin/python -c "from codegen.api.pipeline import run_pipeline; run_pipeline()" +``` + +### Report Locations + +- `tmp/docs/reports/summary.json` — 전체 요약 +- `tmp/docs/reports/smoke.json` — smoke test 결과 +- `tmp/docs/reports/validation.json` — validation 결과 +- `tmp/docs/reports/augment.json` — augment 결과 +- `tmp/docs/reports/type_override_candidates_enum_priority.json` — enum override 후보 +- `tmp/docs/reports/manual_enum_review_candidates.json` — 수동 검토 후보 + +### Error Classification + +| Category | Description | Action | +|----------|-------------|--------| +| `request_error` | 파라미터 불일치/누락 | augment_overrides.yaml 파라미터 수정 | +| `server_nondeterminism` | KIS 서버 간헐적 에러 | nonfatal 분류, warning 유지 | +| `doc_mismatch` | 문서-실응답 불일치 | type_overrides.yaml override 후보 | +| `parser_false_positive` | 파서/추론 오탐 | codegen 로직 수정 | + +### Quality Gate + +파이프라인 실행 후 반드시 확인: + +1. `smoke.errors == 0` +2. `validation.errors == 0` +3. `augment.errors == 0` +4. `.venv/bin/python -m pytest -q` 통과 +5. `.venv/bin/ruff check .` 통과 +6. `.venv/bin/ty check` 통과 diff --git a/.agents/agents/override-governance.md b/.agents/agents/override-governance.md new file mode 100644 index 00000000..abb9b391 --- /dev/null +++ b/.agents/agents/override-governance.md @@ -0,0 +1,44 @@ +# override-governance + +Override 후보 분석 및 거버넌스 프로세스 관리 에이전트. + +## Role + +- Override 후보 추출 및 근거 분석 +- `specs/governance/override-policy.md` 기준 준수 검증 +- 승인 메타데이터 생성 (`approved_by`, `reason`, `evidence`) +- HITL 승인 요청 포맷팅 + +## Tools + +Read, Write, Grep, Glob + +## Model + +opus + +## Override Types + +### Type Overrides (`data/overrides/type_overrides.yaml`) + +필드 타입 변경, output_kinds 변경, enum 확장. + +항목 메타데이터 (필수): +- `id` — endpoint UUID +- `changes` — 변경 내용 +- `approved_by` — 승인자 +- `approved_at` — 승인 일자 (YYYY-MM-DD) +- `reason` — 승인 사유 +- `evidence` — 근거 (리포트 경로 또는 payload 샘플) + +### Augment Overrides (`data/overrides/augment_overrides.yaml`) + +smoke test 파라미터 안정화. + +## Governance Checklist + +1. 후보 분석 — 근거와 트레이드오프 명시 +2. 정책 검증 — `specs/governance/override-policy.md` 기준 충족 확인 +3. HITL 제시 — 사용자에게 승인/거부 요청 +4. 반영 — 승인 시 YAML 업데이트 +5. 검증 — 파이프라인 재실행 + quality gate 통과 diff --git a/.agents/agents/srs-writer.md b/.agents/agents/srs-writer.md new file mode 100644 index 00000000..c51b2a30 --- /dev/null +++ b/.agents/agents/srs-writer.md @@ -0,0 +1,52 @@ +# srs-writer + +요구사항 변경 시 SRS 문서 업데이트 에이전트. + +## Role + +- INCOSE 품질 규칙 적용 (shall 문 사용) +- SR → SyRS 변환 +- 추적성 매트릭스 업데이트 (`specs/srs/INDEX.md`) + +## Tools + +Read, Write, Grep, Glob + +## Model + +opus + +## INCOSE Quality Rules + +1. **Singular**: 하나의 요구사항은 하나의 기능만 명시 +2. **Complete**: 필요한 조건, 제약, 검증 방법 포함 +3. **Unambiguous**: "shall" 사용, "should/may" 회피 +4. **Verifiable**: 테스트 가능한 기준 포함 +5. **Traceable**: 상위 요구사항(SR-xxx)으로 추적 가능 + +## SR Format + +```markdown +SR-T001: The SDK shall authenticate with KIS API using OAuth token management. +- Priority: Critical +- Verification: Integration test with demo credentials +- Acceptance: Token auto-refresh within 5s of expiry +``` + +## SyRS Format + +```markdown +SyRS-T001: The SDK shall implement automatic token refresh using /oauth2/tokenP endpoint. +- Traces to: SR-T001 +- Technology: httpx async client (ADR-003) +- Constraint: Token cache must be thread-safe +- Verification: Test with expired token scenario +``` + +## Traceability Matrix + +`specs/srs/INDEX.md`에 요약 매트릭스 유지: + +| SyRS ID | SR ID | Architecture | Status | +|---------|-------|-------------|--------| +| SyRS-T001 | SR-T001 | ADR-003 | Implemented | diff --git a/.agents/skills/api-audit/SKILL.md b/.agents/skills/api-audit/SKILL.md new file mode 100644 index 00000000..bfdcc779 --- /dev/null +++ b/.agents/skills/api-audit/SKILL.md @@ -0,0 +1,52 @@ +# /api-audit + +KIS API 스펙-실응답 정합성 감사 스킬. + +## Description + +KIS API 문서 스펙과 실제 응답 데이터를 비교하여 불일치를 감지하고, 조치를 제안합니다. + +## Arguments + +- `[domain]` — 감사 대상 도메인 (optional). 예: `국내주식`, `해외주식`, `선물옵션` +- `[endpoint-id]` — 특정 endpoint UUID (optional) +- 인수 없으면 전체 감사 + +## Workflow + +### Phase 0: Scope Selection + +감사 대상 선택: +- 전체: 모든 endpoint +- 도메인별: `data/kis/{domain}/` 하위 +- 단일: 특정 endpoint UUID + +### Phase 1: Audit + +스펙 파일 (`data/kis/`) vs 실응답 캐시 (`tmp/docs/augment/`) 비교. + +불일치 패턴 분류: +- `model_type` — output kind 불일치 (문서 single, 실응답 array) +- `missing` — required 필드 조건부 누락 +- `sentinel` — sentinel 값 패턴 (빈 문자열, 0, 00000000) +- `enum_drift` — 문서 미등록 enum 값 유입 + +### Phase 2: Report + +감사 결과 요약: + +``` +API Audit Report +- Scope: [전체 / 도메인 / endpoint] +- Total endpoints audited: N +- Issues found: N + - model_type: N + - missing: N + - sentinel: N + - enum_drift: N + +Recommendations: +- SRS update candidates: N +- Override candidates: N +- Code fix candidates: N +``` diff --git a/.agents/skills/explore-kis-api/SKILL.md b/.agents/skills/explore-kis-api/SKILL.md new file mode 100644 index 00000000..24503f16 --- /dev/null +++ b/.agents/skills/explore-kis-api/SKILL.md @@ -0,0 +1,46 @@ +# /explore-kis-api + +KIS API 레퍼런스 탐색 스킬. + +## Description + +KIS API 레퍼런스 문서(`data/kis/`)를 탐색하여 endpoint 정보, 요청/응답 구조, 파라미터를 조회합니다. + +## Arguments + +- `[keyword]` — 검색 키워드 (endpoint 이름, 경로, 기능 설명) +- `[category]` — 카테고리 (국내주식, 해외주식, 국내선물옵션, 해외선물옵션, 장내채권) + +## Workflow + +### Search + +키워드 또는 카테고리로 문서 검색: + +``` +data/kis/ +├── 국내주식/ — 국내 주식 시세, 주문, 계좌 +├── 해외주식/ — 해외 주식 시세, 주문, 계좌 +├── 국내선물옵션/ — 국내 선물/옵션 +├── 해외선물옵션/ — 해외 선물/옵션 +├── 장내채권/ — 장내 채권 +├── OAuth인증/ — 인증/토큰 +├── FAQ/ — 자주 묻는 질문 +└── 종목정보파일/ — 마스터 데이터 파일 스펙 +``` + +### Output + +endpoint 정보 요약: +- Endpoint name +- UUID +- HTTP method + path +- TR ID (demo/real) +- Request parameters (type, required, description) +- Response fields (type, description) + +## Usage Examples + +- `/explore-kis-api 투자자` — 투자자 관련 endpoint 검색 +- `/explore-kis-api 해외주식 시세` — 해외주식 시세 endpoint 검색 +- `/explore-kis-api e27baf2f` — 특정 UUID로 endpoint 조회 diff --git a/.agents/skills/openspec-apply-change/SKILL.md b/.agents/skills/openspec-apply-change/SKILL.md new file mode 100644 index 00000000..47d4bc24 --- /dev/null +++ b/.agents/skills/openspec-apply-change/SKILL.md @@ -0,0 +1,156 @@ +--- +name: openspec-apply-change +description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. +license: MIT +compatibility: Requires openspec CLI. +metadata: + author: openspec + version: "1.0" + generatedBy: "1.1.1" +--- + +Implement tasks from an OpenSpec change. + +**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes. + +**Steps** + +1. **Select the change** + + If a name is provided, use it. Otherwise: + - Infer from conversation context if the user mentioned a change + - Auto-select if only one active change exists + - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select + + Always announce: "Using change: " and how to override (e.g., `/opsx:apply `). + +2. **Check status to understand the schema** + ```bash + openspec status --change "" --json + ``` + Parse the JSON to understand: + - `schemaName`: The workflow being used (e.g., "spec-driven") + - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others) + +3. **Get apply instructions** + + ```bash + openspec instructions apply --change "" --json + ``` + + This returns: + - Context file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs) + - Progress (total, complete, remaining) + - Task list with status + - Dynamic instruction based on current state + + **Handle states:** + - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change + - If `state: "all_done"`: congratulate, suggest archive + - Otherwise: proceed to implementation + +4. **Read context files** + + Read the files listed in `contextFiles` from the apply instructions output. + The files depend on the schema being used: + - **spec-driven**: proposal, specs, design, tasks + - Other schemas: follow the contextFiles from CLI output + +5. **Show current progress** + + Display: + - Schema being used + - Progress: "N/M tasks complete" + - Remaining tasks overview + - Dynamic instruction from CLI + +6. **Implement tasks (loop until done or blocked)** + + For each pending task: + - Show which task is being worked on + - Make the code changes required + - Keep changes minimal and focused + - Mark task complete in the tasks file: `- [ ]` → `- [x]` + - Continue to next task + + **Pause if:** + - Task is unclear → ask for clarification + - Implementation reveals a design issue → suggest updating artifacts + - Error or blocker encountered → report and wait for guidance + - User interrupts + +7. **On completion or pause, show status** + + Display: + - Tasks completed this session + - Overall progress: "N/M tasks complete" + - If all done: suggest archive + - If paused: explain why and wait for guidance + +**Output During Implementation** + +``` +## Implementing: (schema: ) + +Working on task 3/7: +[...implementation happening...] +✓ Task complete + +Working on task 4/7: +[...implementation happening...] +✓ Task complete +``` + +**Output On Completion** + +``` +## Implementation Complete + +**Change:** +**Schema:** +**Progress:** 7/7 tasks complete ✓ + +### Completed This Session +- [x] Task 1 +- [x] Task 2 +... + +All tasks complete! Ready to archive this change. +``` + +**Output On Pause (Issue Encountered)** + +``` +## Implementation Paused + +**Change:** +**Schema:** +**Progress:** 4/7 tasks complete + +### Issue Encountered + + +**Options:** +1.