ai-ops-cli 0.2.6 → 1.0.2

package/README.ko.md

@@ -0,0 +1,195 @@
+# ai-ops-cli
+
+[English](./README.md)
+
+`ai-ops-cli`는 프로젝트에 AI agent operating layer를 설치하고, 사용자 환경에 agent skills/subagents를 설치하는 CLI입니다.
+
+이 문서는 현재 구현된 breaking model을 설명합니다. old rules + skills scaffolder 모델은 deprecated 문맥으로만 남깁니다.
+
+## Current Breaking Model
+
+```mermaid
+flowchart TD
+  init["ai-ops init"] --> layer["Project operating layer 설치"]
+  layer --> entry["AGENTS.md canonical entrypoint"]
+  layer --> adapters["GEMINI.md / CLAUDE.md adapters"]
+  layer --> docs["docs/agent/* / docs/business/*"]
+  layer --> state[".ai-ops/manifest.json / context-layer.json"]
+
+  skill["ai-ops skill ..."] --> globalSkills["Global skills only"]
+  subagent["ai-ops subagent ..."] --> globalSubagents["Global subagents only"]
+  pack["ai-ops pack ..."] --> docsSpecs["optional docs/specs/ pack"]
+```
+
+핵심 경계:
+
+- 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 repo:
+
+```text
+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
+docs/agent/rules/stop-rules.md
+docs/agent/checks/impact-checklist.md
+docs/agent/checks/review-checklist.md
+docs/agent/maps/codebase-map.md
+docs/business/business-rules.md
+docs/docs-status.md
+.ai-ops/manifest.json
+.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
+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
+ai-ops [command]
+
+Commands:
+  init       Install or refresh the project agent operating layer
+  diff       Show drift in the project operating layer
+  update     Re-apply the project operating layer
+  audit      Check frontmatter, docs-status, manifest, and context-layer consistency
+  uninstall  Remove project-managed operating layer files
+  skill      Manage global agent skills
+  subagent   Manage global agent subagents
+  pack       Manage optional project operating layer packs
+```
+
+`--tool`은 유지합니다. Codex, Claude Code, Gemini CLI가 서로 다른 discovery 위치와 adapter 파일을 사용하기 때문입니다.
+
+Skill lifecycle 명령:
+
+```bash
+ai-ops skill list
+ai-ops skill install skill-load-check --tool codex
+ai-ops skill install doc-impact-reviewer --tool codex
+ai-ops skill diff
+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도 하지 않습니다.
+
+Subagent lifecycle 명령:
+
+```bash
+ai-ops subagent list
+ai-ops subagent install security-gate --tool codex
+ai-ops subagent diff
+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`에만 기록합니다.
+
+Pack lifecycle 명령:
+
+```bash
+ai-ops init --tool codex
+ai-ops pack list
+ai-ops pack install spec-lifecycle
+ai-ops pack diff spec-lifecycle
+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로만 기록됩니다.
+
+## Deprecated Old Model
+
+다음 동작은 현재 코드나 과거 README에 남아 있을 수 있지만 새 계약에서는 제거 대상입니다.
+
+- preset-first init UX
+- project scope skill 설치
+- `ai-ops skill install --project`
+- project-installed skill metadata
+- `.ai-ops-manifest.json`
+- legacy manifest migration
+- root `specs/`
+- `ai-ops spec init`
+
+기존 프로젝트 자동 마이그레이션은 제공하지 않습니다. 기존 사용자는 old CLI로 `ai-ops uninstall`을 실행한 뒤 새 major CLI로 `ai-ops init`을 다시 실행합니다.
+
+## Old Model Command Notes
+
+Deprecated old model 문맥에서만 아래 명령을 과거 project scope skill 설치 예시로 남깁니다. 현재 skill CLI는 global-only이며 `--project`, `--global`, `--scope`를 공개 옵션으로 제공하지 않습니다.
+
+```bash
+ai-ops skill install skill-load-check --project --tool codex
+```
+
+Deprecated old model 문맥에서만 유지되는 항목:
+
+- `--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입니다.
+
+## 개발
+
+저장소 루트 기준:
+
+```bash
+npm install
+npm run build
+npm run compile
+npm test
+```
+
+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`을 함께 사용합니다.
+
+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` 상태만 확인합니다.
+
+## 관련 문서
+
+- [Master blueprint](../../docs/plan.md)
+- [Implementation playbook](../../docs/implementation-playbook.md)

package/README.md

@@ -1,86 +1,85 @@
 # ai-ops-cli
 
-CLI for managing core AI tool rules and agent skills across projects.
+[Korean](./README.ko.md)
 
-## Why this exists
+`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.
 
-`ai-ops-cli` reduces configuration drift across AI coding tools.
+This document describes the currently implemented breaking model. The old rules + skills scaffolder model remains only as deprecated context.
 
-- different tools use different file layouts and loading models
-- manual sync across tools is error-prone over time
-- teams need a deterministic setup for shared core rules and installable skills
+## Current Breaking Model
 
-The CLI treats these as separate sources of truth:
+```mermaid
+flowchart TD
+  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/*"]
+  layer --> state[".ai-ops/manifest.json / context-layer.json"]
 
-- `apps/cli/data/rules/*.yaml`: always-loaded core rules only
-- `apps/cli/data/skills/skill-registry.json`: install/catalog metadata for skills
-- `apps/cli/data/skills/reference-skills/<skill-id>/`: installable reference skills
-- `apps/cli/data/skills/task-skills/<skill-id>/`: installable task skills
-- `apps/cli/data/presets.yaml`: preset-to-core-rule mapping
+  skill["ai-ops skill ..."] --> globalSkills["Global skills only"]
+  subagent["ai-ops subagent ..."] --> globalSubagents["Global subagents only"]
+  pack["ai-ops pack ..."] --> docsSpecs["optional docs/specs/ pack"]
+```
 
-## What this CLI provides
+Core boundaries:
 
-- interactive project initialization (`ai-ops init`)
-- skill package installation and lifecycle management (`ai-ops skill ...`)
-- spec pipeline directory scaffolding (`ai-ops spec init`)
-- source drift checks (`ai-ops diff`)
-- deterministic re-apply (`ai-ops update`)
-- managed cleanup (`ai-ops uninstall`)
+- 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.
 
-## Supported tools and output layout
+## Install Targets
 
-| Tool                        | Project rules output                                  | Skill output                 |
-| --------------------------- | ----------------------------------------------------- | ---------------------------- |
-| Claude Code (`claude-code`) | `.claude/rules/<rule-id>.md`, `<workspace>/CLAUDE.md` | `.claude/skills/<skill-id>/` |
-| Codex (`codex`)             | `AGENTS.md`, `<workspace>/AGENTS.override.md`         | `.agents/skills/<skill-id>/` |
-| Gemini CLI (`gemini`)       | `GEMINI.md`, `<workspace>/GEMINI.md`                  | `.agents/skills/<skill-id>/` |
+Project repo:
 
-Optional settings files:
+```text
+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
+docs/agent/rules/stop-rules.md
+docs/agent/checks/impact-checklist.md
+docs/agent/checks/review-checklist.md
+docs/agent/maps/codebase-map.md
+docs/business/business-rules.md
+docs/docs-status.md
+.ai-ops/manifest.json
+.ai-ops/context-layer.json
+```
 
-- Claude Code: `.claude/settings.local.json`
-- Gemini CLI: `.gemini/settings.json`
-- Formatting protection section: `.prettierignore`
+`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`.
 
-## Install
+Global tool home:
 
-```bash
-npm install -g ai-ops-cli
+```text
+skills/*
+subagents/*
 ```
 
-## Usage
+## Editing FAQ
 
-```bash
-# Initialize the current project
-ai-ops init
+### What does `ai-ops update` overwrite?
 
-# Install a skill globally (user scope by default)
-ai-ops skill install skill-load-check --tool codex
+`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.
 
-# Install a skill only for the current project
-ai-ops skill install skill-load-check --project --tool codex
+`.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.
 
-# Inspect or update installed skills
-ai-ops skill list
-ai-ops skill diff
-ai-ops skill update
-ai-ops skill uninstall skill-load-check
+### Which files should users edit directly?
 
-# Check project drift
-ai-ops diff
+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.
 
-# Re-apply current project state
-ai-ops update
-ai-ops update --force
+`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.
 
-# Remove project-managed files
-ai-ops uninstall
+### Where should project-specific agent rules go?
 
-# Initialize spec pipeline directory structure
-ai-ops spec init
+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.
 
-# Force re-create even if specs/ already exists
-ai-ops spec init --force
-```
+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
 
@@ -88,137 +87,109 @@ ai-ops spec init --force
 ai-ops [command]
 
 Commands:
-  init       Initialize AI tool rules for a project
-  skill      Manage agent skills
-  spec       Manage spec pipeline
-  update     Update installed rules
-  diff       Show diff between installed and current rules
-  uninstall  Remove installed rules and manifest
-
-Options:
-  --force        Force update even when no changes are detected (update only)
-  -V, --version  Output version number
-  -h, --help     Display help
+  init       Install or refresh the project agent operating layer
+  diff       Show drift in the project operating layer
+  update     Re-apply the project operating layer
+  audit      Check frontmatter, docs-status, manifest, and context-layer consistency
+  uninstall  Remove project-managed operating layer files
+  skill      Manage global agent skills
+  subagent   Manage global agent subagents
+  pack       Manage optional project operating layer packs
 ```
 
-### `ai-ops spec` subcommands
+`--tool` remains because Codex, Claude Code, and Gemini CLI use different discovery locations and adapter files.
 
-```text
-ai-ops spec init [options]
-
-  Initialize the specs/ directory structure for AI-collaborative spec pipelines.
-  Creates:
-    specs/README.md          — usage guide
-    specs/baseline/          — baseline spec documents
-    specs/delta/             — delta (incremental change) spec documents
+Skill lifecycle commands:
 
-Options:
-  --force   Overwrite existing specs/ directory
+```bash
+ai-ops skill list
+ai-ops skill install skill-load-check --tool codex
+ai-ops skill install doc-impact-reviewer --tool codex
+ai-ops skill diff
+ai-ops skill update
+ai-ops skill uninstall skill-load-check
 ```
 
-Notes:
-
-- Project installation state is tracked in `.ai-ops-manifest.json`.
-- User-scope skill state is tracked in `~/.ai-ops/skills-manifest.json`.
-- `ai-ops skill` defaults to user scope. Use `--project` to keep a skill local to the current repo.
+`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.
 
-## Install / Update / Uninstall Behavior
+Subagent lifecycle commands:
 
-- Managed project rule files are wrapped in an `ai-ops` section with metadata (`sourceHash`, `generatedAt`).
-- If a rule file already has an `ai-ops` section, only that section is replaced.
-- If a rule file has no managed section, generated content is appended and user content is preserved.
-- Skill packages are written into dedicated directories and replaced as full package trees on update.
-- `uninstall` removes only project-managed rule files and project-installed skill directories.
-- User-scope skills are never removed by `ai-ops uninstall`.
+```bash
+ai-ops subagent list
+ai-ops subagent install security-gate --tool codex
+ai-ops subagent diff
+ai-ops subagent update
+ai-ops subagent uninstall security-gate
+```
 
-## Init Flow Summary
+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`.
 
-`ai-ops init` prompts for:
+Pack lifecycle commands:
 
-1. Tool selection (`claude-code`, `codex`, `gemini`)
-2. Monorepo confirmation
-3. Workspace selection for monorepos
-4. Preset selection per workspace
-5. Locked core rules review
-6. Preset-linked `reference` skills only:
-   - already-installed global skills are shown separately
-   - only installable skills can be deselected
-7. One shared install scope for selected installable skills (`user` default or `project`)
-8. Optional settings installation
+```bash
+ai-ops init --tool codex
+ai-ops pack list
+ai-ops pack install spec-lifecycle
+ai-ops pack diff spec-lifecycle
+ai-ops pack update spec-lifecycle
+ai-ops pack uninstall spec-lifecycle
+```
 
-Important behavior:
+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.
 
-- core rules come from the preset directly and are not fine-tuned in `init`
-- `init` shows only preset-linked `reference` skills
-- `task` skills are excluded from `init` and are managed with `ai-ops skill install/uninstall`
-- globally available skills are not reinstalled by default
-- when `user` scope is chosen, selected skills are written only to the global skill registry
-- when `project` scope is chosen, selected skills are recorded in `.ai-ops-manifest.json`
+## Deprecated Old Model
 
-Skill authoring rules live in `apps/cli/data/skills/README.md`.
+The following behaviors may still appear in current code or older docs, but they are outside the new contract:
 
-## Local Development
+- preset-first init UX
+- project-scope skill installation
+- `ai-ops skill install --project`
+- project-installed skill metadata
+- `.ai-ops-manifest.json`
+- legacy manifest migration
+- root `specs/`
+- `ai-ops spec init`
 
-From repo root:
+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.
 
-```bash
-npm install
-npm run build
-npm run compile
-npm test
-```
+## Old Model Command Notes
 
-From `apps/cli` workspace:
+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
-npm run build --workspace=apps/cli
-npm run test --workspace=apps/cli
+ai-ops skill install skill-load-check --project --tool codex
 ```
 
-## Local Skill Loading Check
+Deprecated old-model-only items:
+
+- `--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.
 
-Use the built-in `skill-load-check` task skill before publishing to npm.
+## Development
 
-Recommended local flow:
+From the repository root:
 
 ```bash
-# 1. Build the CLI
+npm install
 npm run build
-
-# 2. Use an isolated user home so you do not pollute your real ~/.agents or ~/.claude
-export AI_OPS_HOME="$(mktemp -d)"
-
-# 3. Install the sample skill globally
-node apps/cli/dist/bin/index.js skill install skill-load-check --tool codex
-
-# 4. Verify files exist
-find "$AI_OPS_HOME/.agents/skills/skill-load-check" -maxdepth 2 -type f | sort
-
-# 5. Run the sample script manually
-node "$AI_OPS_HOME/.agents/skills/skill-load-check/scripts/loaded.js"
-```
-
-Expected output:
-
-```text
-A Skill loaded
+npm run compile
+npm test
 ```
 
-Project-scope verification:
+To check only the CLI workspace:
 
 ```bash
-node apps/cli/dist/bin/index.js skill install skill-load-check --project --tool codex
-find ./.agents/skills/skill-load-check -maxdepth 2 -type f | sort
-node ./.agents/skills/skill-load-check/scripts/loaded.js
+npm run build --workspace=apps/cli
+npm run test --workspace=apps/cli
 ```
 
-After file placement is verified, use a real tool prompt that should trigger `skill-load-check` and confirm the tool discovers the skill metadata. If the tool caches skill discovery, restart that tool session before re-checking.
+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`.
 
-## Related Docs
-
-- Master blueprint: [`docs/plan.md`](../../docs/plan.md)
-- Implementation playbook: [`docs/implementation-playbook.md`](../../docs/implementation-playbook.md)
+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.
 
-## License
+## Related Docs
 
-MIT
+- [Master blueprint](../../docs/plan.md)
+- [Implementation playbook](../../docs/implementation-playbook.md)

package/data/context-layer/AGENTS.md

@@ -0,0 +1,30 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - before_task
+update_when:
+  - operating_layer_changes
+---
+# Agent Operating Layer
+
+이 파일은 이 프로젝트의 canonical agent entrypoint다. 도구별 adapter가 있더라도 운영 판단은 이 파일과 `docs/agent/*` 문서를 기준으로 한다.
+
+## 읽기 순서
+
+1. `AGENTS.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`
+
+## 문서 신뢰도
+
+- `Active`: 현재 판단 근거로 사용할 수 있다.
+- `Reserved`: 자리만 만든 문서다. 프로젝트가 보강하기 전까지 현재 판단 근거로 사용하지 않는다.
+- `Draft`: 작성 중인 문서다. 사용 전 검토가 필요하다.
+- `Archived`: 과거 기록이다. 현재 운영 판단에 사용하지 않는다.
+
+문서 상태가 애매하면 `docs/docs-status.md`와 각 문서 frontmatter를 함께 확인한다.

package/data/context-layer/CLAUDE.md

@@ -0,0 +1,14 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - before_task
+update_when:
+  - adapter_changes
+---
+# Claude Code Adapter
+
+이 파일은 Claude Code가 프로젝트 운영 계층을 찾기 위한 adapter다.
+
+작업 전 `AGENTS.md`를 canonical entrypoint로 읽고, 세부 운영 문서는 `docs/agent/*`와 `docs/docs-status.md`를 따른다. 이 파일에는 중복 운영 규칙을 추가하지 않는다.

package/data/context-layer/GEMINI.md

@@ -0,0 +1,14 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - before_task
+update_when:
+  - adapter_changes
+---
+# Gemini CLI Adapter
+
+이 파일은 Gemini CLI가 프로젝트 운영 계층을 찾기 위한 adapter다.
+
+작업 전 `AGENTS.md`를 canonical entrypoint로 읽고, 세부 운영 문서는 `docs/agent/*`와 `docs/docs-status.md`를 따른다. 이 파일에는 중복 운영 규칙을 추가하지 않는다.

package/data/context-layer/docs/agent/checks/impact-checklist.md

@@ -0,0 +1,16 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - before_finish
+update_when:
+  - checklist_changes
+---
+# Impact Checklist
+
+- 공개 CLI 표면이 바뀌었는가?
+- 상태 파일 schema나 경로가 바뀌었는가?
+- 기존 사용자 파일 보존 정책에 영향이 있는가?
+- update/diff/uninstall 동작이 서로 같은 추적 기준을 쓰는가?
+- 실패 시 사용자가 복구할 수 있는 메시지를 받는가?

package/data/context-layer/docs/agent/checks/review-checklist.md

@@ -0,0 +1,17 @@
+---
+status: Active
+layer: agent
+owner: ai-ops
+read_when:
+  - review
+  - before_finish
+update_when:
+  - checklist_changes
+---
+# Review Checklist
+
+- 계획 문서의 의도와 실제 diff가 어긋나는 지점이 있는가?
+- 테스트가 잡지 못하는 런타임 회귀 위험이 있는가?
+- create-only 파일과 managed section 파일의 보존 정책이 섞이지 않았는가?
+- manifest, context-layer, 실제 파일 상태가 같은 기준으로 갱신되는가?
+- 검증 명령이 변경 범위에 충분히 직접적인가?