ai-ops-cli 0.2.6 → 1.0.2

package/data/skills/task-skills/spec-shared-glossary-sync/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: spec-shared-glossary-sync
+description: Create or update a Korean 01_glossary.md inside the current project's docs/specs/baseline directory by standardizing domain terms, entities, states, UI labels, and English code-facing names across baseline docs and active .codex/plans.
+disable-model-invocation: true
+---
+
+# spec-shared-glossary-sync
+
+Use this skill when the project needs a shared glossary or when existing docs/specs/plans have begun to drift in terminology.
+
+Typical high-value run points are:
+
+- after `brief`
+- after `product spec`
+- after `ui spec`
+- during `spec-baseline-sync` if implemented terminology changed
+- whenever naming drift is noticed
+
+Usually skip automatic reruns after small plans unless new shared terminology was introduced.
+
+## Output Location
+
+- Write into the current workspace.
+- Default output path: `./docs/specs/baseline/01_glossary.md`
+
+## Language Rules
+
+- Write the glossary in Korean.
+- Keep code-facing English identifiers, API field names, library/service names, protocol names, file paths, and standard technical terms in their natural English form when clearer.
+- Do not invent awkward Koreanized spellings for standard English technical terms.
+- If a term needs explanation, keep the standard term and add a short Korean definition.
+
+## Objective
+
+Maintain one canonical vocabulary so briefs, specs, UI docs, plans, packets, and baseline sync entries use the same terms for the same concepts.
+
+The default output style is:
+
+- tables first for fast scanning
+- detailed subsections only for genuinely complex concepts
+- diagrams only when relationships or state vocabularies are hard to understand in prose
+
+## Create Or Update Rules
+
+- If `./docs/specs/baseline/01_glossary.md` does not exist, create it from currently approved specs and relevant active plans.
+- If it exists, update it instead of replacing it blindly.
+- Preserve stable canonical terms unless there is a strong reason to change them.
+- If a newly found term conflicts with an existing definition, keep the current canonical term and record the conflict in `정의 충돌 / 검토 필요`.
+- Normalize synonyms toward one preferred term.
+- Prefer Korean for user-facing/domain wording, but keep standard English when clearer, more stable, or already established in the project.
+
+## Recommended Inputs
+
+Read relevant files that exist:
+
+- `./docs/specs/baseline/00_brief.md`
+- `./docs/specs/baseline/05_technical-context.md`
+- `./docs/specs/baseline/10_product-spec.md`
+- `./docs/specs/baseline/20_ui-spec.md`
+- active `./.codex/plans/*.md` when terminology from a current change needs to become canonical
+- `./docs/specs/initial-build/<topic>/30_work-packets/*.md` when reviewing initial build terminology
+- existing `./docs/specs/baseline/01_glossary.md`
+
+Use only files that are present and relevant.
+
+## Workflow
+
+1. Identify repeated nouns, states, and labels across available docs.
+2. Separate true domain concepts from incidental wording.
+3. Choose one canonical project term per concept.
+4. Attach English code-facing counterpart when needed.
+5. Capture harmless synonyms only when useful.
+6. List discouraged or banned wording when ambiguity is likely.
+7. Write most glossary content as tables.
+8. Move only hard cases into detailed sections.
+9. Update the glossary without deleting still-valid prior decisions.
+
+Use these references while drafting:
+
+- [references/template.md](references/template.md)
+- [references/checklist.md](references/checklist.md)
+
+## Required Sections
+
+- `핵심 용어`
+- `엔티티 용어`
+- `상태 용어`
+- `UI 용어`
+- `금지하거나 피할 표현`
+- `복잡한 개념 상세 설명`
+- `정의 충돌 / 검토 필요`
+
+## Quality Bar
+
+The glossary is not ready if:
+
+- simple vocabulary that should be in tables is expanded into unnecessary prose
+- the same concept still appears under multiple primary names
+- terms are listed without definitions
+- code-facing English names and canonical project terms conflict without explanation
+- banned or confusing wording is omitted despite clear ambiguity
+- existing approved terminology is overwritten without explanation

package/data/skills/task-skills/spec-shared-glossary-sync/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "spec-shared-glossary-sync"
+  short_description: "Standardize Korean spec terms into a shared baseline glossary."
+  default_prompt: "Use $spec-shared-glossary-sync to create or update a Korean 01_glossary.md that standardizes terms across baseline docs and active .codex/plans."
+policy:
+  allow_implicit_invocation: false

package/data/skills/task-skills/spec-shared-glossary-sync/references/checklist.md

@@ -0,0 +1,36 @@
+# Glossary Sync Checklist
+
+Use this checklist before finalizing `01_glossary.md`.
+
+## Look For
+
+- one concept described with multiple Korean names
+- one Korean term mapped to multiple English code names
+- UI copy that conflicts with domain terms
+- product docs and change docs using different names for the same thing
+- states that appear in packets but were never defined centrally
+
+## Prefer
+
+- a table-first structure for most vocabulary
+- one canonical project term per concept
+- prefer Korean for user-facing/domain nouns, but keep standard English when that is clearer or already the stable norm
+- one code-facing English name per canonical concept when possible
+- short definitions that explain scope, not implementation
+- explicit “do not use” wording for risky ambiguities
+- detailed prose only for genuinely complex concepts
+
+## 대표 예시
+
+- 플랜 / 루틴 / 프로그램
+- 운동 세션 / 운동 기록 / workout
+- 세트 템플릿 / 세트 기록
+- 저장 / 완료 / 확정
+- 초안 / 진행 중 / 임시 저장
+
+## Update Rule
+
+- merge new terms into the existing glossary
+- do not delete stable terms unless they are clearly wrong
+- when uncertain, add the conflict to `정의 충돌 / 검토 필요`
+- keep simple terms in tables; avoid turning the whole glossary into long prose

package/data/skills/task-skills/spec-shared-glossary-sync/references/template.md

@@ -0,0 +1,58 @@
+# 01_glossary.md Template
+
+```md
+# 01 Glossary
+
+용어 표기 원칙:
+
+- `용어` 칼럼은 한국어 우선이지만, 업계 표준 영어가 더 명확하면 영어 원형을 그대로 쓴다.
+- `소스 오브 트루스` 같은 어색한 음역 대신 `source of truth` 또는 한국어 설명형 표현을 사용한다.
+
+## 핵심 용어
+
+| 용어 | 영문 / 코드명 | 정의 | 사용 범위 | 허용 별칭 | 금지 표현 | 관련 문서 |
+|---|---|---|---|---|---|---|
+| 용어 1 | `termName` | 짧은 정의 | brief / spec / ui | 별칭 1 | 금지 표현 1 | `10_product-spec.md` |
+
+## 엔티티 용어
+
+| 용어 | 영문 / 코드명 | 정의 | 사용 범위 | 허용 별칭 | 금지 표현 | 관련 문서 |
+|---|---|---|---|---|---|---|
+| 엔티티 1 | `entityName` | 짧은 정의 | spec / packet | 별칭 1 | 금지 표현 1 | `10_product-spec.md` |
+
+## 상태 용어
+
+| 용어 | 영문 / 코드명 | 정의 | 사용 범위 | 허용 별칭 | 금지 표현 | 관련 문서 |
+|---|---|---|---|---|---|---|
+| 상태 1 | `draft` | 짧은 정의 | spec / ui / packet | 별칭 1 | 금지 표현 1 | `10_product-spec.md` |
+
+## UI 용어
+
+| 용어 | 영문 / 코드명 | 정의 | 사용 범위 | 허용 별칭 | 금지 표현 | 관련 문서 |
+|---|---|---|---|---|---|---|
+| UI 용어 1 | `labelName` | 짧은 정의 | ui / packet | 별칭 1 | 금지 표현 1 | `20_ui-spec.md` |
+
+## 금지하거나 피할 표현
+
+| 표현 | 이유 | 대신 사용할 표현 |
+|---|---|---|
+| 표현 1 | 왜 피해야 하는지 | 표준 표현 |
+
+## 복잡한 개념 상세 설명
+
+### 개념 1
+
+- 왜 이 개념이 표만으로는 충분하지 않은지 설명
+- 어떤 문맥에서 다른 표현과 충돌하는지 설명
+
+```mermaid
+flowchart TD
+    A["개념 A"] --> B["개념 B"]
+```
+
+## 정의 충돌 / 검토 필요
+
+| 항목 | 현재 표준 | 충돌 표현 | 판단 메모 |
+|---|---|---|---|
+| 충돌 항목 | 현재 표준 표현 | 새로 발견된 표현 | 판단 메모 |
+```

package/data/subagents/README.ko.md

@@ -0,0 +1,49 @@
+# Subagent 작성 가이드
+
+[English](./README.md)
+
+이 디렉터리는 global agent subagent의 source of truth입니다.
+
+## 디렉터리 구조
+
+```text
+apps/cli/data/subagents/
+  README.md
+  README.ko.md
+  subagent-registry.json
+  <subagent-id>/
+    PROMPT.md
+    claude.frontmatter.yaml
+    codex.frontmatter.toml
+    gemini.frontmatter.yaml
+```
+
+## 작성 규칙
+
+1. `subagent-registry.json`만 catalog 노출 여부를 결정합니다.
+2. `id`와 세 frontmatter의 `name`은 모두 같은 kebab-case 값이어야 합니다.
+3. `supported_tools`는 `claude-code`, `codex`, `gemini` 중 하나 이상이어야 합니다.
+4. `PROMPT.md`는 도구 공통 developer instruction 본문입니다.
+5. Claude/Gemini는 YAML frontmatter와 `PROMPT.md`를 합친 Markdown 파일로 렌더링됩니다.
+6. Codex는 TOML metadata, `developer_instructions`, `[[skills.config]]`로 렌더링됩니다.
+7. Codex `skill_names`는 최종 파일에 그대로 남기지 않고 `AI_OPS_HOME/.agents/skills/<skill>/SKILL.md` 절대 경로로 변환합니다.
+8. 필요한 skill이 없어도 설치는 실패하지 않습니다. CLI는 경고만 출력합니다.
+9. subagent는 항상 global tool home에만 설치합니다. project repo에는 `.codex/agents`, `.claude/agents`, `.gemini/agents`, `.ai-ops/subagents-manifest.json`을 만들지 않습니다.
+
+## Registry 필드
+
+| 필드 | 필수 | 예시 | 의미 |
+| --- | --- | --- | --- |
+| `id` | 예 | `security-gate` | canonical subagent id |
+| `supported_tools` | 예 | `["claude-code", "codex", "gemini"]` | 설치 가능한 도구 목록 |
+| `source_path` | 예 | `security-gate` | 상대 source 디렉터리 |
+
+## 출력 경로
+
+| 도구 | 출력 경로 |
+| --- | --- |
+| Codex | `.codex/agents/<id>.toml` |
+| Claude Code | `.claude/agents/<id>.md` |
+| Gemini CLI | `.gemini/agents/<id>.md` |
+
+상태 파일은 `.ai-ops/subagents-manifest.json`입니다. Skill 상태 파일인 `.ai-ops/skills-manifest.json`과 서로 읽거나 쓰지 않습니다.

package/data/subagents/README.md

@@ -0,0 +1,49 @@
+# Subagent Authoring Guide
+
+[Korean](./README.ko.md)
+
+This directory is the source of truth for global agent subagents.
+
+## Directory Shape
+
+```text
+apps/cli/data/subagents/
+  README.md
+  README.ko.md
+  subagent-registry.json
+  <subagent-id>/
+    PROMPT.md
+    claude.frontmatter.yaml
+    codex.frontmatter.toml
+    gemini.frontmatter.yaml
+```
+
+## Authoring Rules
+
+1. Only `subagent-registry.json` decides whether a subagent is exposed in the catalog.
+2. `id` and the `name` in all three frontmatter files must be the same kebab-case value.
+3. `supported_tools` must contain at least one of `claude-code`, `codex`, or `gemini`.
+4. `PROMPT.md` is the shared developer instruction body for all tools.
+5. Claude/Gemini render as Markdown files that combine YAML frontmatter with `PROMPT.md`.
+6. Codex renders as TOML metadata, `developer_instructions`, and `[[skills.config]]`.
+7. Codex `skill_names` are not kept verbatim in the final file; they are converted to absolute `AI_OPS_HOME/.agents/skills/<skill>/SKILL.md` paths.
+8. Installation does not fail when required skills are missing. The CLI only prints a warning.
+9. Subagents are always installed only in the global tool home. The project repo must not receive `.codex/agents`, `.claude/agents`, `.gemini/agents`, or `.ai-ops/subagents-manifest.json`.
+
+## Registry Fields
+
+| Field             | Required | Example                              | Meaning                   |
+| ----------------- | -------- | ------------------------------------ | ------------------------- |
+| `id`              | Yes      | `security-gate`                      | Canonical subagent id     |
+| `supported_tools` | Yes      | `["claude-code", "codex", "gemini"]` | Tools that can install it |
+| `source_path`     | Yes      | `security-gate`                      | Relative source directory |
+
+## Output Paths
+
+| Tool        | Output path               |
+| ----------- | ------------------------- |
+| Codex       | `.codex/agents/<id>.toml` |
+| Claude Code | `.claude/agents/<id>.md`  |
+| Gemini CLI  | `.gemini/agents/<id>.md`  |
+
+The state file is `.ai-ops/subagents-manifest.json`. It is separate from the skill state file, `.ai-ops/skills-manifest.json`; neither lifecycle reads or writes the other.

package/data/subagents/security-gate/PROMPT.md

@@ -0,0 +1,18 @@
+You are `security-gate`, a lightweight security triage subagent.
+
+Your job is to decide whether the provided spec artifact or code change needs deeper security review.
+
+Use the loaded `spec-security-01-triage` skill as the source of truth. Prefer compact Korean output and fail closed:
+
+- if a clear high-risk trigger exists, require review
+- if the change is obviously low-risk, allow no-review
+- if anything is ambiguous, return `UNSURE` and treat it as review-required
+
+Do not perform a full security review unless the parent explicitly asks for one. Focus on triage only:
+
+- decide `mode=spec` or `mode=code` from the parent request
+- identify the concrete triggers
+- list required controls briefly
+- say whether follow-up review is required
+
+Output should stay short and structured around the triage contract.

package/data/subagents/security-gate/claude.frontmatter.yaml

@@ -0,0 +1,8 @@
+name: security-gate
+description: Decide whether a spec artifact or code change needs deeper security review.
+tools: Read, Glob, Grep
+model: haiku
+permissionMode: plan
+maxTurns: 6
+skills:
+  - spec-security-01-triage

package/data/subagents/security-gate/codex.frontmatter.toml

@@ -0,0 +1,6 @@
+name = "security-gate"
+description = "Decide whether a spec artifact or code change needs deeper security review."
+model = "gpt-5.4-mini"
+model_reasoning_effort = "low"
+sandbox_mode = "read-only"
+skill_names = ["spec-security-01-triage"]

package/data/subagents/security-gate/gemini.frontmatter.yaml

@@ -0,0 +1,6 @@
+name: security-gate
+description: Decide whether a spec artifact or code change needs deeper security review.
+kind: local
+model: gemini-3-flash-preview
+temperature: 0
+max_turns: 6

package/data/subagents/security-reviewer/PROMPT.md

@@ -0,0 +1,17 @@
+You are `security-reviewer`, a focused security review subagent.
+
+Use the loaded security skills as the source of truth. Start by checking whether the change is truly review-worthy. If the request is explicitly for security review, or if triage is `REVIEW_REQUIRED` or `UNSURE`, perform the full review.
+
+Your review must stay findings-first, severity-first, and in Korean.
+
+Focus on material security risks such as:
+
+- authentication and authorization gaps
+- sensitive data exposure
+- unsafe input handling, injection, or template/rendering issues
+- SSRF or unsafe external fetch behavior
+- file upload/download risks
+- tenant isolation and destructive action safety
+- missing security-relevant validation, auditability, or regression coverage
+
+Do not spend time on style or general cleanup unless no material issue exists. If no deep review is needed, say that briefly and explain why.

package/data/subagents/security-reviewer/claude.frontmatter.yaml

@@ -0,0 +1,9 @@
+name: security-reviewer
+description: Review a code or contract change for material security risks and missing controls.
+tools: Read, Glob, Grep
+model: sonnet
+permissionMode: plan
+maxTurns: 10
+skills:
+  - spec-security-01-triage
+  - spec-security-02-review

package/data/subagents/security-reviewer/codex.frontmatter.toml

@@ -0,0 +1,6 @@
+name = "security-reviewer"
+description = "Review a code or contract change for material security risks and missing controls."
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+skill_names = ["spec-security-01-triage", "spec-security-02-review"]

package/data/subagents/security-reviewer/gemini.frontmatter.yaml

@@ -0,0 +1,6 @@
+name: security-reviewer
+description: Review a code or contract change for material security risks and missing controls.
+kind: local
+model: gemini-3-pro-preview
+temperature: 0
+max_turns: 10

package/data/subagents/subagent-registry.json

@@ -0,0 +1,14 @@
+{
+  "subagents": [
+    {
+      "id": "security-gate",
+      "supported_tools": ["claude-code", "codex", "gemini"],
+      "source_path": "security-gate"
+    },
+    {
+      "id": "security-reviewer",
+      "supported_tools": ["claude-code", "codex", "gemini"],
+      "source_path": "security-reviewer"
+    }
+  ]
+}