ai-ops-cli 1.0.1 → 1.0.3

package/README.ko.md

@@ -1,5 +1,7 @@
 # ai-ops-cli
 
+[English](./README.md)
+
 `ai-ops-cli`는 프로젝트에 AI agent operating layer를 설치하고, 사용자 환경에 agent skills/subagents를 설치하는 CLI입니다.
 
 이 문서는 현재 구현된 breaking model을 설명합니다. old rules + skills scaffolder 모델은 deprecated 문맥으로만 남깁니다.
@@ -36,6 +38,7 @@ Project repo:
 AGENTS.md
 GEMINI.md
 CLAUDE.md
+docs/agent/rules/00-agent-baseline.md
 docs/agent/workflow.md
 docs/agent/rules/routing-rules.md
 docs/agent/rules/doc-update-rules.md
@@ -49,6 +52,8 @@ docs/docs-status.md
 .ai-ops/context-layer.json
 ```
 
+`docs/agent/rules/00-agent-baseline.md`는 기존 `role-persona`, `communication`, `code-philosophy`, `naming-convention`, `plan-mode`의 기본 의도를 새 operating layer 문서로 이관한 Active 규칙입니다. `AGENTS.md` 직후 먼저 읽습니다.
+
 Global tool home:
 
 ```text
@@ -56,6 +61,26 @@ skills/*
 subagents/*
 ```
 
+## 수정 FAQ
+
+### `ai-ops update`가 덮어쓰는 파일은 무엇인가요?
+
+`AGENTS.md`, `GEMINI.md`, `CLAUDE.md`, `docs/agent/rules/*`, `docs/agent/checks/*`, `docs/agent/workflow.md`는 ai-ops managed 문서입니다. 이 파일의 `<!-- ai-ops:start -->`부터 `<!-- ai-ops:end -->`까지는 CLI 템플릿 영역이고, `ai-ops update` 때 현재 CLI 템플릿으로 다시 적용됩니다. 사용자가 이 영역을 직접 수정하면 다음 update에서 유지되지 않습니다.
+
+`.ai-ops/manifest.json`과 `.ai-ops/context-layer.json`도 직접 편집 대상이 아닙니다. 각각 설치 상태와 문서 index를 기록하는 CLI 상태 파일입니다.
+
+### 사용자가 직접 수정해야 하는 파일은 무엇인가요?
+
+프로젝트 지식은 project-owned 문서에 적습니다. 기본 project-owned 문서는 `docs/agent/maps/codebase-map.md`, `docs/business/business-rules.md`, `docs/docs-status.md`입니다. `docs/agent/maps/codebase-map.md`와 `docs/business/business-rules.md`는 처음에는 Reserved 템플릿이지만, 프로젝트가 실제 내용을 채운 뒤에는 update가 자동으로 덮어쓰지 않습니다.
+
+`docs/docs-status.md`는 project-owned 문서이지만 자유 메모장이 아니라 context-layer registry입니다. 문서 status/frontmatter를 바꿀 때 함께 맞추는 파일이며, update 과정에서 manifest와 실제 문서 frontmatter 기준으로 테이블이 정리될 수 있습니다.
+
+### 프로젝트 고유 agent rule은 어디에 적나요?
+
+현재 기본 layer에는 프로젝트 구조와 비즈니스 규칙을 담는 project-owned 문서가 있지만, 프로젝트별 agent 행동 규칙만을 위한 별도 Active 문서는 아직 first-class 템플릿으로 열려 있지 않습니다. 그래서 `AGENTS.md`의 managed 영역이나 tool adapter에 직접 규칙을 추가하는 방식은 update-safe한 계약이 아닙니다.
+
+프로젝트별 agent rule을 안정적으로 지원하려면 `docs/agent/rules/project-rules.md` 같은 project-owned Active 문서를 추가하고, manifest/context-layer/docs-status가 함께 추적하도록 제품 계약을 확장하는 것이 다음 개선 후보입니다.
+
 ## 목표 CLI 표면
 
 ```text

package/README.md

@@ -1,14 +1,16 @@
 # ai-ops-cli
 
-`ai-ops-cli`는 프로젝트에 AI agent operating layer를 설치하고, 사용자 환경에 agent skills/subagents를 설치하는 CLI입니다.
+[Korean](./README.ko.md)
 
-이 문서는 현재 구현된 breaking model을 설명합니다. old rules + skills scaffolder 모델은 deprecated 문맥으로만 남깁니다.
+`ai-ops-cli` installs an AI agent operating layer into a project and installs reusable agent skills/subagents into the user's global tool environment.
+
+This document describes the currently implemented breaking model. The old rules + skills scaffolder model remains only as deprecated context.
 
 ## Current Breaking Model
 
 ```mermaid
 flowchart TD
-  init["ai-ops init"] --> layer["Project operating layer 설치"]
+  init["ai-ops init"] --> layer["Install project operating layer"]
   layer --> entry["AGENTS.md canonical entrypoint"]
   layer --> adapters["GEMINI.md / CLAUDE.md adapters"]
   layer --> docs["docs/agent/* / docs/business/*"]
@@ -19,16 +21,16 @@ flowchart TD
   pack["ai-ops pack ..."] --> docsSpecs["optional docs/specs/ pack"]
 ```
 
-핵심 경계:
+Core boundaries:
 
-- project scope는 operating layer 문서만 관리합니다.
-- global scope는 skills/subagents만 관리합니다.
-- `AGENTS.md`가 canonical entrypoint입니다.
-- `GEMINI.md`와 `CLAUDE.md`는 `AGENTS.md`를 기준으로 삼게 하는 adapter입니다.
-- `docs/specs/`는 optional pack 위치입니다.
-- global asset 명령은 `AI_OPS_HOME` 또는 `HOME`이 없으면 cwd fallback 없이 실패합니다.
+- Project scope manages only operating-layer documents.
+- Global scope manages only skills/subagents.
+- `AGENTS.md` is the canonical entrypoint.
+- `GEMINI.md` and `CLAUDE.md` are adapters that point tools back to `AGENTS.md`.
+- `docs/specs/` is the optional pack location.
+- Global asset commands require `AI_OPS_HOME` or `HOME`; they fail closed without cwd fallback when neither exists.
 
-## 설치 대상
+## Install Targets
 
 Project repo:
 
@@ -36,6 +38,7 @@ Project repo:
 AGENTS.md
 GEMINI.md
 CLAUDE.md
+docs/agent/rules/00-agent-baseline.md
 docs/agent/workflow.md
 docs/agent/rules/routing-rules.md
 docs/agent/rules/doc-update-rules.md
@@ -49,6 +52,8 @@ docs/docs-status.md
 .ai-ops/context-layer.json
 ```
 
+`docs/agent/rules/00-agent-baseline.md` is the Active rule that carries the original intent of the old `role-persona`, `communication`, `code-philosophy`, `naming-convention`, and `plan-mode` rules into the new operating layer. It is read immediately after `AGENTS.md`.
+
 Global tool home:
 
 ```text
@@ -56,7 +61,27 @@ skills/*
 subagents/*
 ```
 
-## 목표 CLI 표면
+## Editing FAQ
+
+### What does `ai-ops update` overwrite?
+
+`AGENTS.md`, `GEMINI.md`, `CLAUDE.md`, `docs/agent/rules/*`, `docs/agent/checks/*`, and `docs/agent/workflow.md` are ai-ops managed documents. In these files, the region from `<!-- ai-ops:start -->` through `<!-- ai-ops:end -->` is CLI template content. `ai-ops update` reapplies the current CLI template to that region. User edits inside that region are not preserved across update.
+
+`.ai-ops/manifest.json` and `.ai-ops/context-layer.json` are also not direct-edit files. They are CLI state files for installation state and document indexing.
+
+### Which files should users edit directly?
+
+Project knowledge belongs in project-owned documents. The default project-owned documents are `docs/agent/maps/codebase-map.md`, `docs/business/business-rules.md`, and `docs/docs-status.md`. `docs/agent/maps/codebase-map.md` and `docs/business/business-rules.md` start as Reserved templates, but once the project fills them with real content, update does not automatically overwrite them.
+
+`docs/docs-status.md` is project-owned, but it is not a free-form notebook. It is the context-layer registry. Update it together with document status/frontmatter changes; the update flow may also normalize its table from the manifest and current document frontmatter.
+
+### Where should project-specific agent rules go?
+
+The default layer currently has project-owned documents for project structure and business rules, but it does not yet provide a first-class Active template for project-specific agent behavior rules. Because of that, adding rules inside the managed region of `AGENTS.md` or inside a tool adapter is not an update-safe contract.
+
+To support project-specific agent rules safely, the next product extension should add a project-owned Active document such as `docs/agent/rules/project-rules.md` and have the manifest, context-layer index, and docs-status table track it together.
+
+## CLI Surface
 
 ```text
 ai-ops [command]
@@ -72,9 +97,9 @@ Commands:
   pack       Manage optional project operating layer packs
 ```
 
-`--tool`은 유지합니다. Codex, Claude Code, Gemini CLI가 서로 다른 discovery 위치와 adapter 파일을 사용하기 때문입니다.
+`--tool` remains because Codex, Claude Code, and Gemini CLI use different discovery locations and adapter files.
 
-Skill lifecycle 명령:
+Skill lifecycle commands:
 
 ```bash
 ai-ops skill list
@@ -85,9 +110,9 @@ ai-ops skill update
 ai-ops skill uninstall skill-load-check
 ```
 
-`doc-impact-reviewer`는 변경 완료 또는 커밋 직전에 운영 문서 영향도를 확인하는 수동 task skill입니다. `$doc-impact-reviewer`로 호출하면 git status/diff를 보고 `required / recommended / not needed` 문서 후보와 미갱신 리스크를 제안합니다. 사용자 승인 전에는 문서를 수정하지 않고, 직접 staging/commit도 하지 않습니다.
+`doc-impact-reviewer` is a manual task skill for checking operating-document impact near the end of work or before commit. Invoking `$doc-impact-reviewer` reads git status/diff and reports document update candidates as `required / recommended / not needed`. It does not edit documents, stage files, or commit before user approval.
 
-Subagent lifecycle 명령:
+Subagent lifecycle commands:
 
 ```bash
 ai-ops subagent list
@@ -97,9 +122,9 @@ ai-ops subagent update
 ai-ops subagent uninstall security-gate
 ```
 
-Subagent는 항상 global tool home에 설치됩니다. Codex는 `.codex/agents/<id>.toml`, Claude Code는 `.claude/agents/<id>.md`, Gemini CLI는 `.gemini/agents/<id>.md`를 사용하고, 상태는 `.ai-ops/subagents-manifest.json`에만 기록합니다.
+Subagents are always installed into the global tool home. Codex uses `.codex/agents/<id>.toml`, Claude Code uses `.claude/agents/<id>.md`, Gemini CLI uses `.gemini/agents/<id>.md`, and state is recorded only in `.ai-ops/subagents-manifest.json`.
 
-Pack lifecycle 명령:
+Pack lifecycle commands:
 
 ```bash
 ai-ops init --tool codex
@@ -110,14 +135,14 @@ ai-ops pack update spec-lifecycle
 ai-ops pack uninstall spec-lifecycle
 ```
 
-`spec-lifecycle` pack은 `docs/specs/README.md`, `docs/specs/README.ko.md`, `docs/specs/baseline/.gitkeep`, `docs/specs/initial-build/.gitkeep`를 설치합니다. Markdown 문서만 context-layer와 `docs/docs-status.md` 감사 대상이고, `.gitkeep`은 manifest의 일반 pack file로만 기록됩니다.
+The `spec-lifecycle` pack installs `docs/specs/README.md`, `docs/specs/README.ko.md`, `docs/specs/baseline/.gitkeep`, and `docs/specs/initial-build/.gitkeep`. Only Markdown documents are audited by the context-layer and `docs/docs-status.md`; `.gitkeep` files are tracked only as regular pack files in the manifest.
 
 ## Deprecated Old Model
 
-다음 동작은 현재 코드나 과거 README에 남아 있을 수 있지만 새 계약에서는 제거 대상입니다.
+The following behaviors may still appear in current code or older docs, but they are outside the new contract:
 
 - preset-first init UX
-- project scope skill 설치
+- project-scope skill installation
 - `ai-ops skill install --project`
 - project-installed skill metadata
 - `.ai-ops-manifest.json`
@@ -125,26 +150,26 @@ ai-ops pack uninstall spec-lifecycle
 - root `specs/`
 - `ai-ops spec init`
 
-기존 프로젝트 자동 마이그레이션은 제공하지 않습니다. 기존 사용자는 old CLI로 `ai-ops uninstall`을 실행한 뒤 새 major CLI로 `ai-ops init`을 다시 실행합니다.
+Existing projects are not migrated automatically. Existing users should run `ai-ops uninstall` with the old CLI, then run `ai-ops init` again with the new major CLI.
 
 ## Old Model Command Notes
 
-Deprecated old model 문맥에서만 아래 명령을 과거 project scope skill 설치 예시로 남깁니다. 현재 skill CLI는 global-only이며 `--project`, `--global`, `--scope`를 공개 옵션으로 제공하지 않습니다.
+The command below remains only as a deprecated old-model example for historical project-scope skill installation. The current skill CLI is global-only and does not expose `--project`, `--global`, or `--scope` as public options.
 
 ```bash
 ai-ops skill install skill-load-check --project --tool codex
 ```
 
-Deprecated old model 문맥에서만 유지되는 항목:
+Deprecated old-model-only items:
 
-- `--project`는 project scope skill 설치용 old option입니다.
-- `--global`, `--scope`는 skill scope를 직접 지정하던 old option입니다.
-- `spec init`은 root `specs/`를 만들던 제거된 old command입니다.
-- `.ai-ops-manifest.json`는 old project manifest입니다.
+- `--project` was the old option for project-scope skill installation.
+- `--global` and `--scope` were old options for directly selecting skill scope.
+- `spec init` was the removed old command that created root `specs/`.
+- `.ai-ops-manifest.json` was the old project manifest.
 
-## 개발
+## Development
 
-저장소 루트 기준:
+From the repository root:
 
 ```bash
 npm install
@@ -153,18 +178,18 @@ npm run compile
 npm test
 ```
 
-CLI workspace만 확인할 때:
+To check only the CLI workspace:
 
 ```bash
 npm run build --workspace=apps/cli
 npm run test --workspace=apps/cli
 ```
 
-코드와 운영 문서 변경은 `npm run check`를 기본 검증으로 사용합니다. CLI 배포 산출물 확인은 `npm run build`와 `npm run compile`을 함께 사용합니다.
+Use `npm run check` as the default validation for code and operating-document changes. For CLI release artifacts, run both `npm run build` and `npm run compile`.
 
-Self-dogfood 검증은 `npm run build` 후 이 repo에 `init --tool codex --tool gemini --tool claude-code`를 적용하고, `diff`, `audit`, `update --force`, `uninstall --yes`, 재-`init`, 재-`audit` 순서로 확인합니다. 이 repo에는 `spec-lifecycle` pack을 설치하지 않고 `pack list`에서 `not installed` 상태만 확인합니다.
+Self-dogfood validation runs `npm run build`, applies `init --tool codex --tool gemini --tool claude-code` to this repo, then checks `diff`, `audit`, `update --force`, `uninstall --yes`, re-`init`, and re-`audit`. This repo does not install the `spec-lifecycle` pack during self-dogfood; `pack list` only verifies the `not installed` state.
 
-## 관련 문서
+## Related Docs
 
 - [Master blueprint](../../docs/plan.md)
 - [Implementation playbook](../../docs/implementation-playbook.md)

package/data/context-layer/AGENTS.md

@@ -14,10 +14,11 @@ update_when:
 ## 읽기 순서
 
 1. `AGENTS.md`
-2. `docs/agent/workflow.md`
-3. `docs/agent/rules/*.md`
-4. 작업 성격에 맞는 `docs/agent/checks/*.md`
-5. `docs/docs-status.md`
+2. `docs/agent/rules/00-agent-baseline.md`
+3. `docs/agent/workflow.md`
+4. 나머지 `docs/agent/rules/*.md`
+5. 작업 성격에 맞는 `docs/agent/checks/*.md`
+6. `docs/docs-status.md`
 
 ## 문서 신뢰도
 

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/packs/spec-lifecycle/docs/specs/README.ko.md

@@ -9,6 +9,8 @@ update_when:
 ---
 # Specs
 
+[English](./README.md)
+
 이 문서는 Reserved 상태입니다. 프로젝트가 실제 spec lifecycle 문서를 보강하기 전까지 현재 판단 근거로 사용하지 마세요.
 
 ## 디렉토리 구조

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

@@ -9,6 +9,8 @@ update_when:
 ---
 # 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

package/data/skills/README.ko.md

@@ -1,5 +1,7 @@
 # Skill 작성 가이드
 
+[English](./README.md)
+
 이 디렉터리는 설치 가능한 agent skill의 source of truth입니다.
 
 ## 용어

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

package/data/subagents/README.ko.md

@@ -1,5 +1,7 @@
 # Subagent 작성 가이드
 
+[English](./README.md)
+
 이 디렉터리는 global agent subagent의 source of truth입니다.
 
 ## 디렉터리 구조

package/data/subagents/README.md

@@ -1,5 +1,7 @@
 # Subagent Authoring Guide
 
+[Korean](./README.ko.md)
+
 This directory is the source of truth for global agent subagents.
 
 ## Directory Shape