ai-ops-cli 0.2.6 → 1.0.2

package/data/context-layer/docs/agent/maps/codebase-map.md

@@ -0,0 +1,16 @@
+---
+status: Reserved
+layer: agent
+owner: project
+read_when:
+  - codebase_navigation
+update_when:
+  - architecture_changes
+---
+# Codebase Map
+
+이 문서는 Reserved 상태입니다. 프로젝트가 실제 구조를 보강하기 전까지 현재 판단 근거로 사용하지 마세요.
+
+## 주요 영역
+
+- TBD

package/data/context-layer/docs/agent/rules/00-agent-baseline.md

@@ -0,0 +1,47 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - before_task
+update_when:
+  - baseline_rule_changes
+---
+# Agent Baseline Rules
+
+이 문서는 모든 작업 전에 먼저 적용할 기본 협업 규칙이다. 세부 routing, workflow, stop rule보다 앞서 읽고, 프로젝트별 Active 문서가 더 구체적인 판단 근거를 제공하면 그 문서를 우선한다.
+
+## 협업 태도
+
+- 사용자를 초보자로 낮춰 설명하지 않는다.
+- 사용자는 senior developer라고 가정하되, 특정 도메인이나 패턴에 익숙하지 않을 수 있음을 고려한다.
+- 패턴, 라이브러리, 아키텍처를 고를 때는 중요한 선택 이유를 짧게 설명한다.
+- 아키텍처, edge case, 성능, 유지보수성을 우선해 판단한다.
+
+## 커뮤니케이션
+
+- "Certainly", "Of course", "Here is the code", "I understand", "Great question" 같은 filler phrase로 시작하지 않는다.
+- 사용자가 명시적으로 영어를 요청하지 않는 한, 코드와 inline code comment를 제외한 응답은 한국어로 작성한다.
+- 불확실한 내용은 단정하지 않고 확인 가능한 근거, 추론, 남은 리스크를 구분한다.
+
+## 코드 철학
+
+- clever하거나 opaque한 코드보다 의도가 드러나는 명시적인 코드를 우선한다.
+- Rule of Three 이전에는 공통 abstraction을 서두르지 않는다.
+- core business logic에는 side effect를 섞지 않고, functional core / imperative shell 구조를 선호한다.
+- 상태 변경은 가능한 한 immutable update로 처리한다.
+- 복잡한 business rule은 실패하는 테스트를 먼저 두고 구현한다.
+- 파일 내부 선언은 types, constants, validators/guards, helper functions, main logic/exports 순서로 배치한다.
+- 한 파일에 의미가 다른 그룹이 둘 이상 있으면 `// ----- types -----` 같은 section divider comment로 경계를 표시한다.
+
+## 네이밍
+
+- directory name은 kebab-case를 사용한다.
+- 새 파일과 문서 이름은 역할이 드러나는 구체적인 이름을 사용한다.
+
+## 계획과 다이어그램
+
+- flow, sequence, state, structure를 설명할 때 긴 bullet list보다 Mermaid diagram을 우선 검토한다.
+- UX/control flow와 decision tree는 `flowchart`, request/response와 service interaction은 `sequenceDiagram`, entity/schema relationship은 `erDiagram`, lifecycle/state transition은 `stateDiagram-v2`를 사용한다.
+- Mermaid diagram은 fenced `mermaid` code block으로 작성한다.
+- plan 문서를 저장할 때는 `YYYYMMDD_<topic>.md` 형식을 사용하고, topic은 kebab-case로 작성한다.

package/data/context-layer/docs/agent/rules/doc-update-rules.md

@@ -0,0 +1,22 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - document_change
+update_when:
+  - document_policy_changes
+---
+# Document Update Rules
+
+## 갱신 기준
+
+- 구현 동작이 바뀌면 해당 동작을 설명하는 `Active` 문서를 갱신한다.
+- 문서 상태/frontmatter 관리는 모든 Markdown이 아니라 context-layer와 `docs/docs-status.md`에 등록된 operating-layer 문서를 기준으로 한다.
+- `Reserved` 문서를 실제 판단 근거로 승격하려면 frontmatter와 `docs/docs-status.md`를 함께 갱신한다.
+- 오래된 문서는 삭제보다 `Archived` 전환을 우선 검토한다.
+
+## 금지
+
+- project-owned create-only 문서를 자동 update로 덮어쓰지 않는다.
+- 도구 adapter에 canonical 운영 규칙을 중복 작성하지 않는다.

package/data/context-layer/docs/agent/rules/routing-rules.md

@@ -0,0 +1,22 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - before_task
+update_when:
+  - routing_changes
+---
+# Routing Rules
+
+## 판단 순서
+
+1. 요청이 코드 변경인지, 리뷰인지, 문서 정리인지 구분한다.
+2. repo 내부의 계획 문서가 지정되면 실제 diff와 직접 비교한다.
+3. 외부 사실이나 최신 정보가 필요한 경우 현재 출처를 확인한다.
+4. 프로젝트 문서가 `Reserved`이면 현재 사실로 인용하지 않는다.
+
+## 범위
+
+- project scope: `AGENTS.md`, `GEMINI.md`, `CLAUDE.md`, `docs/agent/*`, `docs/business/*`, `docs/docs-status.md`, `.ai-ops/*`
+- global scope: skills, subagents, tool-specific reusable assets

package/data/context-layer/docs/agent/rules/stop-rules.md

@@ -0,0 +1,20 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - before_destructive_action
+  - before_external_side_effect
+update_when:
+  - safety_policy_changes
+---
+# Stop Rules
+
+## 멈추고 확인할 때
+
+- 삭제, reset, 강제 overwrite처럼 복구가 어려운 작업이 필요한 경우
+- credential, 개인 정보, 운영 데이터가 노출될 수 있는 경우
+- 계획 문서와 실제 코드 구조가 충돌해 임의 판단이 위험한 경우
+- 검증 실패 원인이 환경 문제인지 구현 문제인지 구분되지 않는 경우
+
+확인이 필요한 지점은 짧게 설명하고, 안전한 대안이 있으면 함께 제시한다.

package/data/context-layer/docs/agent/workflow.md

@@ -0,0 +1,25 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - before_task
+update_when:
+  - workflow_changes
+---
+# Workflow
+
+## 기본 흐름
+
+1. 요청 범위와 현재 작업 디렉터리를 확인한다.
+2. 관련 문서의 `status`를 확인하고 `Active` 문서만 판단 근거로 사용한다.
+3. 코드 변경 전 현재 diff를 확인한다.
+4. 변경은 가능한 작은 단위로 적용한다.
+5. 변경 범위에 맞는 검증을 실행한다.
+6. 결과, 검증, 남은 리스크를 짧게 보고한다.
+
+## 보존 원칙
+
+- 사용자 변경으로 보이는 diff는 되돌리지 않는다.
+- project-owned 문서는 CLI update가 덮어쓰지 않는다.
+- global skills와 subagents는 project operating layer uninstall 대상이 아니다.

package/data/context-layer/docs/business/business-rules.md

@@ -0,0 +1,16 @@
+---
+status: Reserved
+layer: business
+owner: project
+read_when:
+  - business_rule_check
+update_when:
+  - business_rule_changes
+---
+# Business Rules
+
+이 문서는 Reserved 상태입니다. 프로젝트가 실제 규칙을 보강하기 전까지 현재 판단 근거로 사용하지 마세요.
+
+## 규칙
+
+- TBD

package/data/context-layer/docs/docs-status.md

@@ -0,0 +1,14 @@
+---
+status: Active
+layer: status
+owner: project
+read_when:
+  - before_task
+update_when:
+  - document_status_changes
+---
+# Docs Status
+
+| path | status | owner |
+| --- | --- | --- |
+{{documents_table}}

package/data/packs/pack-registry.json

@@ -0,0 +1,8 @@
+{
+  "packs": [
+    {
+      "id": "spec-lifecycle",
+      "source_path": "spec-lifecycle"
+    }
+  ]
+}

package/data/packs/spec-lifecycle/docs/specs/README.ko.md

@@ -0,0 +1,28 @@
+---
+status: Reserved
+layer: spec
+owner: project
+read_when:
+  - spec_lifecycle
+update_when:
+  - spec_lifecycle_changes
+---
+# Specs
+
+[English](./README.md)
+
+이 문서는 Reserved 상태입니다. 프로젝트가 실제 spec lifecycle 문서를 보강하기 전까지 현재 판단 근거로 사용하지 마세요.
+
+## 디렉토리 구조
+
+```text
+docs/specs/
+├── baseline/
+└── initial-build/
+```
+
+## 기준
+
+- `baseline/`은 승인된 제품/기술/UI 기준 문서를 둡니다.
+- `initial-build/`는 초기 구현 work packet과 관련 산출물을 둡니다.
+- 실제 판단 근거로 쓰기 전에 각 문서의 frontmatter와 `docs/docs-status.md` 상태를 갱신합니다.

package/data/packs/spec-lifecycle/docs/specs/README.md

@@ -0,0 +1,28 @@
+---
+status: Reserved
+layer: spec
+owner: project
+read_when:
+  - spec_lifecycle
+update_when:
+  - spec_lifecycle_changes
+---
+# Specs
+
+[Korean](./README.ko.md)
+
+This document is Reserved. Do not use this document as current decision-making evidence until the project fills in real spec lifecycle documents.
+
+## Directory Structure
+
+```text
+docs/specs/
+├── baseline/
+└── initial-build/
+```
+
+## Rules
+
+- `baseline/` contains approved product, technical, and UI baseline documents.
+- `initial-build/` contains initial implementation work packets and related artifacts.
+- Before using any document as decision-making evidence, update its frontmatter and its status in `docs/docs-status.md`.

package/data/packs/spec-lifecycle/docs/specs/baseline/.gitkeep

@@ -0,0 +1 @@
+

package/data/packs/spec-lifecycle/docs/specs/initial-build/.gitkeep

@@ -0,0 +1 @@
+

package/data/skills/README.ko.md

@@ -0,0 +1,184 @@
+# Skill 작성 가이드
+
+[English](./README.md)
+
+이 디렉터리는 설치 가능한 agent skill의 source of truth입니다.
+
+## 용어
+
+### Reference Skill
+
+`reference skill`은 lazy-load되는 지식 pack입니다.
+
+- 정식 상세 내용은 `references/reference.md`에 둡니다.
+- `SKILL.md`는 얇게 유지하고, agent가 언제 skill을 써야 하는지와 무엇을 먼저 읽어야 하는지만 안내합니다.
+- 표준, stack 가이드, 큰 도메인 reference에 사용합니다.
+
+### Task Skill
+
+`task skill`은 절차형 workflow입니다.
+
+- 정식 절차는 `SKILL.md`에 둡니다.
+- `references/`는 선택적인 보조 자료입니다.
+- 반복 가능한 점검, 작업, guided workflow에 사용합니다.
+
+### Task Skill 사용
+
+반복되는 운영 절차는 task skill로 둡니다. 예를 들어 `doc-impact-reviewer`는 변경 완료 또는 커밋 직전에 diff를 확인하고, 갱신 후보 문서를 `required / recommended / not needed`로 제안한 뒤 사용자 승인 후 승인된 문서만 수정합니다.
+
+승인이 필요한 task skill은 자동 호출을 막습니다.
+
+- Codex: `agents/openai.yaml`에 `policy.allow_implicit_invocation: false`를 둡니다.
+- Claude Code: `SKILL.md` frontmatter에 `disable-model-invocation: true`를 둡니다.
+- Gemini CLI: skill-level explicit-only flag가 없으므로 본문에 명시 호출 전용 규칙을 적습니다.
+
+설치 예시:
+
+```bash
+ai-ops skill install doc-impact-reviewer --tool codex
+```
+
+## 디렉터리 구조
+
+```text
+apps/cli/data/skills/
+  README.md
+  README.ko.md
+  skill-registry.json
+  reference-skills/
+    <skill-name>/
+      SKILL.md
+      agents/       # optional
+      references/   # required for reference skills
+      assets/       # optional
+      scripts/      # optional
+  task-skills/
+    <skill-name>/
+      SKILL.md
+      references/   # optional
+      assets/       # optional
+      scripts/      # optional
+```
+
+## 작성 규칙
+
+1. 디렉터리 이름은 frontmatter `name`과 정확히 일치해야 합니다.
+2. `SKILL.md`는 YAML frontmatter로 시작해야 합니다.
+3. `kind`, `supported_tools`, preset grouping, `source_path`는 `skill-registry.json`에 둡니다.
+4. `reference` skill은 `reference-skills/` 아래에 두고 `references/reference.md`를 포함해야 합니다.
+5. `task` skill은 `task-skills/` 아래에 두고 실행 절차를 `SKILL.md`에 둡니다.
+6. 같은 상세 내용을 `SKILL.md`와 `references/`에 중복하지 않습니다.
+7. 도구별 metadata는 skill source 안에 직접 작성하고 CLI가 그대로 복사합니다.
+8. Codex와 Gemini는 `.agents/skills/<skill-name>`에 설치합니다. Claude는 `.claude/skills/<skill-name>`에 설치합니다.
+9. CLI는 skill 디렉터리 트리 전체를 그대로 복사하므로 `agents/`, `references/`, `assets/`, `scripts/` 아래 파일은 변경 없이 설치됩니다.
+
+## Frontmatter 필드
+
+`SKILL.md` frontmatter는 이제 agent-facing 용도입니다. CLI는 아래 필수 필드를 검증하고, 추가 도구별 frontmatter 필드는 무시합니다.
+
+| 필드 | 필수 | 예시 | 의미 |
+| --- | --- | --- | --- |
+| `name` | 예 | `graphql-contract` | 고유 skill 이름과 설치 디렉터리 key |
+| `description` | 예 | `Use when changing GraphQL schema contracts.` | discovery/autotrigger 요약 |
+
+## Registry 필드
+
+`skill-registry.json`은 install/catalog SSOT입니다.
+
+| 필드 | 필수 | 예시 | 의미 |
+| --- | --- | --- | --- |
+| `id` | 예 | `graphql-contract` | canonical skill id |
+| `kind` | 예 | `reference` / `task` | skill category |
+| `supported_tools` | 예 | `["claude-code", "codex", "gemini"]` | 설치 가능한 도구 |
+| `groups` | 예 | `["frontend-web"]` | 표시/discovery grouping |
+| `included_in_presets` | 예 | `["frontend-web", "backend-ts"]` | `ai-ops init`에서 이 skill을 노출하는 preset |
+| `source_path` | 예 | `reference-skills/graphql-contract` | skill source가 있는 상대 디렉터리 |
+
+## Content 배치
+
+### Reference Skill
+
+- `SKILL.md`: 짧은 routing note
+- `references/reference.md`: 전체 상세 내용
+
+### Task Skill
+
+- `SKILL.md`: 실행 가능한 전체 절차
+- `references/`: 선택적인 배경 자료
+- `scripts/`: 선택적인 실행 helper
+
+## 도구별 호출 제어
+
+skill을 explicit-only로 만들어야 하면 skill 작성자가 도구별 metadata를 직접 추가해야 합니다.
+
+### Codex
+
+`agents/openai.yaml`을 직접 만듭니다.
+
+```yaml
+allow_implicit_invocation: false
+```
+
+- Codex가 description만 보고 skill을 자동 호출하면 안 될 때 사용합니다.
+- CLI가 전체 디렉터리 트리를 복사하므로 `agents/openai.yaml`은 그대로 설치됩니다.
+
+### Claude Code
+
+`SKILL.md` frontmatter에 `disable-model-invocation: true`를 직접 추가합니다.
+
+```yaml
+---
+name: deploy-script
+description: Runs the deployment workflow.
+disable-model-invocation: true
+---
+```
+
+- Claude가 명시적인 `/skill-name` 호출로만 skill을 로드해야 할 때 사용합니다.
+- CLI는 이 추가 frontmatter 필드를 보존하고 자동 생성하지 않습니다.
+
+### Gemini CLI
+
+Gemini CLI는 현재 implicit invocation 비활성화를 위한 skill-level frontmatter flag를 제공하지 않습니다.
+
+- Gemini에서 explicit-only 동작이 필요하면 custom command를 사용합니다.
+- 가짜 Gemini 전용 필드를 `SKILL.md`에 추가하지 마세요. Gemini가 해석하지 않습니다.
+
+## 예시
+
+### Reference Skill Skeleton
+
+```text
+reference-skills/graphql-contract/
+  SKILL.md
+  agents/
+    openai.yaml      # optional
+  references/
+    reference.md
+```
+
+### Task Skill Skeleton
+
+```text
+task-skills/skill-load-check/
+  SKILL.md
+  scripts/
+    loaded.js
+```
+
+## 임시 검증 Skill
+
+`skill-load-check`는 임시 검증 skill 예시입니다.
+
+- description은 좁고 test-focused하게 유지합니다.
+- 본문은 짧고 절차형으로 유지합니다.
+- install/load workflow가 검증된 뒤에는 나중에 삭제해도 됩니다.
+
+## 운영 Task Skill
+
+`doc-impact-reviewer`는 운영 문서 영향도를 수동으로 검토하는 task skill입니다.
+
+- git status, diff, 변경 파일, 관련 operating-layer 문서를 읽습니다.
+- 편집 전에 문서 후보와 리스크를 보고합니다.
+- 사용자 확인 전에는 편집하지 않습니다.
+- staging, commit, hook 설치를 직접 수행하지 않습니다.

package/data/skills/README.md

@@ -1,5 +1,7 @@
 # Skill Authoring Guide
 
+[Korean](./README.ko.md)
+
 This directory is the source of truth for installable agent skills.
 
 ## Terms
@@ -20,11 +22,28 @@ A `task skill` is a procedural workflow.
 - `references/` is optional supporting material only
 - Use it for repeatable checks, actions, and guided workflows
 
+### Task Skill Usage
+
+Keep repeatable operating procedures as task skills. For example, `doc-impact-reviewer` checks the diff when work is finished or just before commit, classifies document update candidates as `required / recommended / not needed`, and edits only the documents the user approves.
+
+Disable automatic invocation for task skills that require explicit approval.
+
+- Codex: add `policy.allow_implicit_invocation: false` to `agents/openai.yaml`.
+- Claude Code: add `disable-model-invocation: true` to the `SKILL.md` frontmatter.
+- Gemini CLI: there is no skill-level explicit-only flag, so write the explicit-invocation rule in the skill body.
+
+Install example:
+
+```bash
+ai-ops skill install doc-impact-reviewer --tool codex
+```
+
 ## Directory Shape
 
 ```text
 apps/cli/data/skills/
   README.md
+  README.ko.md
   skill-registry.json
   reference-skills/
     <skill-name>/
@@ -45,7 +64,7 @@ apps/cli/data/skills/
 
 1. Directory name must exactly match frontmatter `name`.
 2. `SKILL.md` must start with YAML frontmatter.
-3. `kind`, `supported_tools`, `install_scopes`, preset grouping, and `source_path` live in `skill-registry.json`.
+3. `kind`, `supported_tools`, preset grouping, and `source_path` live in `skill-registry.json`.
 4. A `reference` skill must live under `reference-skills/` and include `references/reference.md`.
 5. A `task` skill must live under `task-skills/` and keep its executable procedure in `SKILL.md`.
 6. Do not duplicate the same detailed content across `SKILL.md` and `references/`.
@@ -71,7 +90,6 @@ apps/cli/data/skills/
 | `id`                  | Yes      | `graphql-contract`                   | Canonical skill id                                |
 | `kind`                | Yes      | `reference` / `task`                 | Skill category                                    |
 | `supported_tools`     | Yes      | `["claude-code", "codex", "gemini"]` | Where the skill may be installed                  |
-| `install_scopes`      | Yes      | `["project", "user"]`                | Allowed install scopes                            |
 | `groups`              | Yes      | `["frontend-web"]`                   | Display/discovery grouping                        |
 | `included_in_presets` | Yes      | `["frontend-web", "backend-ts"]`     | Presets that surface this skill in `ai-ops init`  |
 | `source_path`         | Yes      | `reference-skills/graphql-contract`  | Relative directory that contains the skill source |
@@ -155,3 +173,12 @@ task-skills/skill-load-check/
 - Keep the description narrow and test-focused
 - Keep the body short and procedural
 - It is acceptable to delete this skill later once the install/load workflow is proven
+
+## Operating Task Skills
+
+`doc-impact-reviewer` is a task skill for manually reviewing operating-document impact.
+
+- It reads git status, diffs, changed files, and related operating-layer documents.
+- It reports document candidates and risk before editing.
+- It does not edit before user confirmation.
+- It does not stage, commit, or install hooks by itself.