@soddong/agentic-runtime 0.16.0

package/README.md

@@ -0,0 +1,707 @@
+# @soddong/agentic-runtime
+
+`@soddong/agentic-runtime`은 Agentic Platform의 로컬 실행 기반(runtime) 및 CLI 패키지입니다.
+
+이 패키지는 `agentic` 명령을 제공하며, 설치된 domain, capability, application 패키지를 로컬 실행 프로젝트에서 조립하고 실행하기 위한 기반 역할을 합니다.
+
+## 사용자 관점 요약
+
+| 항목 | 내용 |
+| --- | --- |
+| package | `@soddong/agentic-runtime` |
+| CLI | `agentic` |
+| 현재 지원 명령 | `agentic help`, `agentic version`, `agentic init`, `agentic setup`, `agentic docs`, `agentic config`, `agentic run`, `agentic execution list/latest/show/summary`, `agentic hook record`, `agentic db init/status`, `agentic adapter install/status`, `agentic module register/list`, `agentic bundle install/apply/list/status`, `agentic seed import/apply/status`, `agentic project create/status`, `agentic agent register/context` |
+| 예정 명령 | `agentic validate`, `agentic render` |
+
+## Agent 실행 API
+
+Agent module은 `AgentRuntimeClient` 형태로 `run()`을 제공하고, 실행 프로젝트 또는 router는 `runAgentRuntimeClient()`로 실행합니다.
+
+이 방식에서 Agent는 실제 업무 로직만 담당하고, `@soddong/agentic-runtime`은 실행 이력, 사용자 지시, 로그, 결과 저장을 표준화합니다.
+
+```ts
+import { runAgentRuntimeClient } from "@soddong/agentic-runtime";
+
+const agent = {
+  manifest: {
+    agentId: "sample-agent",
+    packageName: "sample-agent-package",
+    packageVersion: "0.1.0",
+    moduleLayer: "application",
+    capabilities: [
+      {
+        capabilityId: "sample.review",
+        description: "요구사항을 검토합니다.",
+        keywords: ["요구사항", "검토"]
+      }
+    ]
+  },
+  run(input, context) {
+    context.logger.info("Agent request received", {
+      requestText: input.requestText
+    });
+
+    return {
+      outputType: "json",
+      contentJson: {
+        ok: true,
+        requestText: input.requestText
+      }
+    };
+  }
+};
+
+const result = await runAgentRuntimeClient(agent, {
+  requestText: "요구사항을 검토해 주세요."
+});
+
+console.log(result.runId);
+```
+
+## Agent Routing API
+
+`@soddong/agentic-runtime`은 concrete domain package를 직접 의존하지 않습니다. 각 agent package가 `@soddong/agentic-capability-agent-client`의 manifest contract를 제공하면, runtime은 등록된 manifest를 기준으로 route decision을 수행합니다.
+
+```ts
+import {
+  registerAgentManifest,
+  routeRegisteredAgents
+} from "@soddong/agentic-runtime";
+import { createAgentManifest } from "@soddong/agentic-capability-agent-client";
+
+const manifest = createAgentManifest({
+  agentId: "document-agent",
+    packageName: "@soddong/agentic-domain-document",
+  packageVersion: "0.1.0",
+  moduleLayer: "application",
+  capabilities: [
+    {
+      capabilityId: "document.create",
+      description: "문서 초안을 생성합니다.",
+      keywords: ["문서", "초안", "작성"]
+    }
+  ]
+});
+
+registerAgentManifest(manifest);
+
+const decision = routeRegisteredAgents({
+  requestText: "요구사항 정의서 초안을 작성해줘"
+});
+
+console.log(decision.selectedAgentId);
+```
+
+domain package가 agent resource index까지 함께 제공하는 경우에는 contribution을 등록합니다.
+
+```ts
+import {
+  assembleRegisteredAgentContext,
+  registerAgentContribution,
+  routeRegisteredAgents,
+  selectRegisteredAgentResources
+} from "@soddong/agentic-runtime";
+import { documentAgentContribution } from "@soddong/agentic-domain-document";
+
+registerAgentContribution(documentAgentContribution);
+
+const decision = routeRegisteredAgents({
+  requestText: "문서 목차와 본문 초안을 작성해줘"
+});
+
+console.log(decision.selectedContribution?.resourceIndex?.title);
+
+const bundle = selectRegisteredAgentResources({
+  requestText: "문서 표 컬럼 헤더를 설계해줘"
+});
+
+console.log(bundle?.bundleType);
+console.log(bundle?.resourceIds);
+
+const context = assembleRegisteredAgentContext(
+  {
+    requestText: "문서 표 컬럼 헤더를 설계해줘"
+  },
+  {
+    packageRoots: {
+      "@soddong/agentic-domain-document": "/path/to/node_modules/agentic-domain-document"
+    }
+  }
+);
+
+console.log(context?.contentText);
+```
+
+1차 routing은 keyword/example 기반 rule scoring입니다. LLM router와 embedding router는 후속 확장 대상입니다.
+
+Agent resource selection도 1차에서는 선택된 contribution의 keyword rule을 실행하는 방식입니다. Runtime은 각 domain package의 파일 의미를 하드코딩하지 않고, 선택된 agent contribution의 `resource-selection.json` 계약만 실행합니다.
+
+Agent context assembly는 선택된 resource file을 실제 Markdown context로 조립한다. Runtime은 package 설치 경로를 임의로 추정하지 않으므로 `packageRoots`를 호출자가 제공해야 한다.
+
+Consumer 프로젝트에서 CLI로 agent contribution을 등록하고 context를 조립하려면 다음 명령을 사용합니다.
+
+```bash
+npx agentic agent register @soddong/agentic-domain-document
+npx agentic agent context "표 컬럼 헤더를 설계하고 3열은 설명으로 해줘"
+npx agentic agent context "표 컬럼 헤더를 설계하고 3열은 설명으로 해줘" --format json
+```
+
+CLI는 consumer 프로젝트의 `node_modules`에서 package root를 찾고, 등록된 module registry를 기준으로 context 조립에 필요한 package root를 연결합니다. 따라서 코드 API처럼 `packageRoots`를 직접 넘기지 않아도 됩니다.
+
+저장되는 주요 정보:
+
+| 구분 | 테이블 | 내용 |
+| --- | --- | --- |
+| 사용자 지시 | `agentic_user_requests` | 지시 원문, 유입 경로, context snapshot |
+| 실행 단위 | `agentic_execution_runs` | 실행 package, agent/command 식별자, 상태, 소요 시간 |
+| 실행 로그 | `agentic_execution_logs` | Agent가 남긴 단계별 로그와 구조화 payload |
+| 실행 결과 | `agentic_execution_outputs` | text/json/file/artifact 결과 |
+
+## 설치
+
+기본 registry는 공식 npm registry입니다.
+
+```bash
+npm install @soddong/agentic-runtime@0.16.0
+```
+
+사용자 `~/.npmrc`에 별도 registry가 남아 있으면 공식 registry를 명시하거나 user config를 정리합니다.
+
+```bash
+npm config set registry https://registry.npmjs.org/ --location=user
+npm install @soddong/agentic-runtime@0.16.0 --registry=https://registry.npmjs.org/
+```
+
+publish 권한이 필요한 사용자는 `~/.npmrc`에 npm token을 설정합니다. token 실값은 문서, source, CI log에 기록하지 않습니다.
+
+```text
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+```
+
+## 실행 확인
+
+```bash
+npx agentic --version
+npx agentic --help
+```
+
+기대 결과:
+
+```text
+@soddong/agentic-runtime 0.16.0
+```
+
+## 프로젝트 초기화
+
+사용자 프로젝트에서 다음 명령을 실행하면 기본 설정 파일과 로컬 작업 디렉터리를 생성합니다.
+
+```bash
+npx agentic init
+```
+
+생성 구조:
+
+```text
+consumer-project/
+  agentic.config.json
+  .agentic/
+    AGENTS.md
+    README.md
+    bin/
+      agentic-hook.mjs
+    data/
+    logs/
+    modules/
+```
+
+설치된 패키지 문서 위치와 현재 프로젝트 설정 상태는 다음 명령으로 확인합니다.
+
+```bash
+npx agentic docs
+npx agentic config
+```
+
+Codex, Kiro, Claude Code adapter까지 함께 준비하려면 통합 setup 명령을 사용합니다.
+
+```bash
+npx agentic setup --adapter codex
+npx agentic setup --adapter kiro
+npx agentic setup --adapter claude-code
+```
+
+`adapter install`을 먼저 실행해도 됩니다. 프로젝트가 아직 초기화되지 않았으면 `adapter install`이 내부에서 `init`과 `db init`을 먼저 수행한 뒤 adapter 설치까지 진행합니다.
+
+```bash
+npx agentic adapter install kiro
+```
+
+`.agentic/AGENTS.md`는 @soddong/agentic-runtime managed block으로 관리됩니다. `init`, `setup`, `adapter install` 실행 시 managed block의 runtime version을 확인하고, 기존 block version이 현재 runtime보다 낮으면 사용자 작성 영역은 유지한 채 managed block만 갱신합니다.
+
+```md
+<!-- agentic-runtime:start version=0.16.0 -->
+...
+<!-- agentic-runtime:end -->
+```
+
+사용자가 직접 작성한 지침은 managed block 밖에 둡니다.
+
+Agent hook은 성능을 위해 `npx`를 매번 호출하지 않고 project-local wrapper를 사용합니다.
+
+```bash
+node .agentic/bin/agentic-hook.mjs --source kiro --event PromptSubmit
+```
+
+파일만 생성하고 Codex CLI marketplace/plugin add는 건너뛰려면 다음을 사용합니다.
+
+```bash
+npx agentic setup --adapter codex --prepare-only
+```
+
+## Runtime Execution 기록
+
+사용자 지시를 runtime execution으로 기록합니다.
+
+```bash
+npx agentic run "요구사항을 검토해 주세요."
+```
+
+현재 `agentic run`은 router 또는 개별 Agent module 실행 전 단계의 공통 기록 기능입니다.
+
+저장되는 위치:
+
+| 정보 | 테이블 |
+| --- | --- |
+| 사용자 지시 | `agentic_user_requests` |
+| 실행 단위 | `agentic_execution_runs` |
+| 실행 로그 | `agentic_execution_logs` |
+| 실행 결과 | `agentic_execution_outputs` |
+
+`agentic init`은 `.agentic/AGENTS.md` 템플릿을 생성합니다. consumer 프로젝트의 루트 `AGENTS.md`에는 이 내용을 반영해, Agentic Platform 관련 지시가 먼저 `npx agentic run "<사용자 지시문>"`으로 기록되도록 운영 정책을 둡니다.
+
+## Runtime Execution 이력 조회
+
+저장된 사용자 지시, 실행 상태, 로그, 결과는 다음 명령으로 조회합니다.
+
+```bash
+npx agentic execution list --range today
+npx agentic execution latest
+npx agentic execution show <run-id>
+npx agentic execution summary --range 7d
+```
+
+Agent나 자동화 도구가 사용하기 쉬운 JSON 출력도 지원합니다.
+
+```bash
+npx agentic execution list --range 7d --format json
+npx agentic execution summary --range today --format json
+npx agentic execution latest --range today --status succeeded --format json
+```
+
+이전 지시, 이전 결과, 마지막 완료 작업을 묻는 경우에는 현재 실행 중인 자기 run을 피하기 위해 `--status succeeded`를 우선 사용합니다.
+
+현재 실행 중인 작업을 묻는 경우에는 `--status running`, 실패 이력을 묻는 경우에는 `--status failed`를 사용합니다.
+
+주요 조회 옵션:
+
+```text
+--range 1h|6h|24h|today|yesterday|7d|30d|this-week|last-week|this-month|last-month
+--from YYYY-MM-DD
+--to YYYY-MM-DD
+--source codex|kiro|claude-code
+--status succeeded
+--limit 20
+--format text|json
+```
+
+Execution timestamp는 UTC 기준으로 저장합니다. SQLite `CURRENT_TIMESTAMP`로 저장된 timezone 없는 `DATETIME` 문자열도 UTC로 해석합니다.
+
+조회 range는 rolling range와 calendar range를 구분합니다.
+
+| range | 기준 |
+| --- | --- |
+| `1h`, `6h`, `24h` | 현재 시각 기준 rolling range |
+| `7d`, `30d` | 현재 시각 기준 rolling range |
+| `today`, `yesterday` | KST calendar day |
+| `this-week`, `last-week` | KST calendar week, 월요일 시작 |
+| `this-month`, `last-month` | KST calendar month |
+
+예를 들어 `today`가 `2026-06-26 KST`이면 SQL 비교 boundary는 `2026-06-25 15:00:00 UTC`부터 `2026-06-26 15:00:00 UTC`까지입니다.
+
+## Codex Adapter
+
+Codex adapter는 Codex `UserPromptSubmit`, `Stop` hook을 통해 사용자 지시와 turn 결과를 `@soddong/agentic-runtime` execution DB에 기록합니다.
+
+Codex adapter는 전역 Codex plugin bridge를 사용합니다. 표준 selector는 `agentic-runtime-codex@agentic-runtime`이며, 실제 기록은 현재 작업 디렉터리에 `agentic.config.json`과 `.agentic/bin/agentic-hook.mjs`가 있는 프로젝트에서만 수행합니다.
+
+설치:
+
+```bash
+npx agentic adapter install codex
+```
+
+상태 확인:
+
+```bash
+npx agentic adapter status codex
+```
+
+이미 설치된 Codex adapter 파일을 현재 `@soddong/agentic-runtime` 버전 기준으로 갱신하려면 `--force`를 사용합니다.
+
+```bash
+npx agentic adapter install codex --force
+codex plugin list
+```
+
+생성 구조:
+
+```text
+consumer-project/
+  plugins/
+    agentic-runtime-codex/
+      .codex-plugin/
+        plugin.json
+      hooks/
+        hooks.json
+      skills/
+        agentic-runtime-usage/
+          SKILL.md
+  .agents/
+    plugins/
+      marketplace.json
+```
+
+Codex가 hook 신뢰 승인을 요구하면 사용자가 내용을 확인하고 승인해야 합니다.
+
+Codex hook command는 프로젝트 로컬 wrapper인 `.agentic/bin/agentic-hook.mjs`가 있을 때만 기록을 수행합니다. wrapper가 없는 프로젝트에서는 성공 상태로 no-op 처리하므로, Codex plugin 등록이 남아 있어도 @soddong/agentic-runtime 미초기화 프로젝트의 turn이 hook 실패로 중단되지 않습니다.
+
+같은 `agentic-runtime-codex` plugin을 여러 marketplace에서 동시에 활성화하지 않습니다. 중복 등록이 있으면 hook이 중복 실행될 수 있으므로 `agentic-runtime-codex@agentic-runtime` 하나만 전역 bridge로 유지합니다.
+
+## Kiro Adapter
+
+Kiro adapter는 Kiro CLI/IDE에서 사용자 지시와 Agent turn 종료를 `@soddong/agentic-runtime` execution DB에 기록하기 위한 설정을 생성합니다.
+
+지원 범위:
+
+| 대상 | 생성/수정 파일 | 비고 |
+| --- | --- | --- |
+| Kiro CLI V3 Early Access | `.kiro/hooks/agentic-runtime.json` | standalone hook 파일, `UserPromptSubmit`/`Stop` trigger 사용 |
+| Kiro CLI V2 | `.kiro/agents/kiro_with_hooks.json` | agent config의 embedded `hooks` 필드 사용 |
+| Kiro IDE | `.kiro/hooks/*.kiro.hook` | IDE 호환용 보조 파일 |
+
+설치:
+
+```bash
+npx agentic adapter install kiro
+```
+
+상태 확인:
+
+```bash
+npx agentic adapter status kiro
+```
+
+이미 생성된 Kiro adapter 파일을 현재 `@soddong/agentic-runtime` 버전 기준으로 갱신하려면 `--force`를 사용합니다.
+
+```bash
+npx agentic adapter install kiro --force
+```
+
+Kiro CLI V2에서 hook agent를 기본값으로 지정하려면 `--set-default`를 명시합니다. 이 옵션은 사용자 Kiro 설정을 변경할 수 있으므로 기본 설치에서는 실행하지 않습니다.
+
+```bash
+npx agentic adapter install kiro --set-default
+```
+
+`--set-default`는 내부적으로 `kiro-cli agent set-default kiro_with_hooks`를 실행합니다. `kiro` 명령이 아니라 `kiro-cli` 명령이어야 하며, agent 이름은 `kito_with_hooks`가 아니라 `kiro_with_hooks`입니다.
+
+직접 확인:
+
+```bash
+kiro-cli agent set-default kiro_with_hooks
+kiro-cli --agent kiro_with_hooks
+```
+
+생성 구조:
+
+```text
+consumer-project/
+  .kiro/
+    agents/
+      kiro_with_hooks.json
+    hooks/
+      agentic-runtime.json
+      agentic-runtime-prompt-submit.kiro.hook
+      agentic-runtime-agent-stop.kiro.hook
+    steering/
+      agentic-runtime.md
+  plugins/
+    agentic-runtime-kiro/
+      README.md
+      hooks/
+        kiro-hook-guide.md
+```
+
+등록되는 command:
+
+| 구분 | Event/Trigger | Command |
+| --- | --- | --- |
+| Kiro CLI V3 | `UserPromptSubmit` | `node .agentic/bin/agentic-hook.mjs --source kiro --event PromptSubmit` |
+| Kiro CLI V3 | `Stop` | `node .agentic/bin/agentic-hook.mjs --source kiro --event AgentStop` |
+| Kiro CLI V2 | `userPromptSubmit` | `node .agentic/bin/agentic-hook.mjs --source kiro --event PromptSubmit` |
+| Kiro CLI V2 | `stop` | `node .agentic/bin/agentic-hook.mjs --source kiro --event AgentStop` |
+| Kiro IDE | Prompt Submit | `node .agentic/bin/agentic-hook.mjs --source kiro --event PromptSubmit` |
+| Kiro IDE | Agent Stop | `node .agentic/bin/agentic-hook.mjs --source kiro --event AgentStop` |
+
+Kiro CLI V3는 현재 Early Access이며 `kiro-cli --v3`로 opt-in 하는 구조입니다. CLI V2는 기존 agent config embedded hook을 사용합니다. Kiro IDE에서 `.kiro/hooks/*.kiro.hook` 파일을 인식하지 못하면 Kiro UI에서 생성된 파일 내용을 기준으로 hook 등록 상태를 확인합니다.
+
+Kiro CLI V2에서 hook을 적용하려면 다음 중 하나로 실행합니다.
+
+```bash
+kiro-cli --agent kiro_with_hooks
+kiro-cli agent set-default kiro_with_hooks
+```
+
+상세한 Kiro CLI/IDE hook 설명은 consumer 프로젝트에 생성되는 다음 파일을 확인합니다.
+
+```bash
+cat plugins/agentic-runtime-kiro/hooks/kiro-hook-guide.md
+```
+
+검증:
+
+```bash
+npx agentic adapter status kiro
+npx agentic execution latest --source kiro --format json
+```
+
+## Claude Code Adapter
+
+Claude Code adapter는 `.claude/settings.json`에 `UserPromptSubmit`, `Stop` command hook을 자동 병합하여 사용자 지시와 turn 종료를 `@soddong/agentic-runtime` execution DB에 기록합니다.
+
+설치:
+
+```bash
+npx agentic adapter install claude-code
+```
+
+상태 확인:
+
+```bash
+npx agentic adapter status claude-code
+```
+
+이미 생성된 Claude Code adapter 파일을 현재 `@soddong/agentic-runtime` 버전 기준으로 갱신하려면 `--force`를 사용합니다.
+
+```bash
+npx agentic adapter install claude-code --force
+```
+
+생성/수정 구조:
+
+```text
+consumer-project/
+  .claude/
+    settings.json
+    rules/
+      agentic-runtime.md
+  plugins/
+    agentic-runtime-claude-code/
+      README.md
+```
+
+등록되는 hook:
+
+| Claude Code hook | Command |
+| --- | --- |
+| UserPromptSubmit | `node .agentic/bin/agentic-hook.mjs --source claude-code --event UserPromptSubmit` |
+| Stop | `node .agentic/bin/agentic-hook.mjs --source claude-code --event Stop` |
+
+## SQLite 초기화
+
+사용자 프로젝트의 로컬 실행 DB를 초기화합니다.
+
+```bash
+npx agentic db init
+npx agentic db status
+```
+
+기본 DB 파일:
+
+```text
+.agentic/platform.sqlite
+```
+
+## Module Registry
+
+실행 프로젝트에서 사용할 Agentic package는 프로젝트 DB에 명시적으로 등록합니다.
+
+```bash
+npx agentic module register sample-agent-package 0.0.1 application
+npx agentic module list
+```
+
+module layer 값:
+
+```text
+runtime
+domain
+capability
+application
+support
+```
+
+## Project Bundle Registry
+
+methodology seed bundle provider package가 설치되어 있으면 runtime에 bundle 설치 상태를 등록할 수 있습니다.
+
+```bash
+npx agentic bundle install @soddong/agentic-methodology-ai-agent-sdlc --bundle ai-agent-sdlc-build-planning
+npx agentic bundle apply @soddong/agentic-methodology-ai-agent-sdlc --bundle ai-agent-sdlc-build-planning
+npx agentic bundle apply @soddong/agentic-methodology-ai-agent-sdlc --bundle ai-agent-sdlc-build-planning --install-required
+npx agentic bundle list
+npx agentic bundle status
+```
+
+`bundle install`은 bundle manifest와 validation 결과를 runtime DB에 등록합니다. 실제 methodology, artifact, document domain DB 반영은 `seed import`로 계획을 만든 뒤 `seed apply`에서 target package handler를 통해 수행합니다.
+
+`bundle apply`는 다음 단계를 한 번에 수행합니다.
+
+```text
+- 프로젝트 runtime init/db init
+- --install-required 지정 시 bundle provider package npm install
+- bundle install
+- --install-required 지정 시 bundle manifest의 requires.packages npm install
+- bundle manifest의 requires.packages 자동 module register
+- seed import
+- seed apply
+```
+
+기본 `bundle apply`는 npm package를 자동 설치하지 않고, 이미 설치된 package만 등록/적용합니다. 사용자 편의 설치까지 포함하려면 `--install-required`를 사용합니다.
+
+```bash
+npx agentic bundle apply @soddong/agentic-methodology-ai-agent-sdlc \
+  --bundle ai-agent-sdlc-build-planning \
+  --install-required
+```
+
+수동 설치를 선호하면 다음처럼 먼저 packages를 설치한 뒤 `bundle apply`를 실행할 수 있습니다.
+
+```bash
+npm install @soddong/agentic-methodology-ai-agent-sdlc @soddong/agentic-domain-methodology @soddong/agentic-domain-artifact-standard @soddong/agentic-contract-validation @soddong/agentic-domain-artifact
+npx agentic bundle apply @soddong/agentic-methodology-ai-agent-sdlc --bundle ai-agent-sdlc-build-planning
+```
+
+## Seed Import Plan
+
+installed bundle을 기준으로 domain package 반영 계획을 dry-run으로 생성합니다.
+
+```bash
+npx agentic seed import --bundle ai-agent-sdlc-build-planning
+npx agentic seed apply --bundle ai-agent-sdlc-build-planning
+npx agentic seed status
+```
+
+`seed import`는 target package 준비 상태를 점검하고 `agentic_seed_import_runs`, `agentic_seed_import_items`에 import plan을 저장합니다. target package가 설치 또는 등록되지 않았으면 해당 item은 `blocked`로 표시합니다.
+
+```text
+Bundle: ai-agent-sdlc-build-planning
+Target: @soddong/agentic-domain-methodology
+Status: blocked
+Reason: package not installed or not registered
+```
+
+`seed import` 단계는 dry-run이며 domain DB에는 쓰지 않습니다. `seed apply`는 생성된 import plan을 기준으로 target package의 `applyAgenticSeed` handler를 호출합니다. target package가 설치 또는 등록되지 않았거나 handler가 없으면 해당 item은 `blocked`로 남습니다.
+
+## Execution Project Lifecycle
+
+`seed apply`가 성공한 bundle은 execution project로 생성할 수 있습니다. 1차 범위의 execution project는 workflow engine이 아니라, bundle의 stage/activity와 primary output artifact 기준을 runtime DB에 snapshot으로 등록하는 lifecycle scaffold입니다.
+
+```bash
+npx agentic project create \
+  --bundle ai-agent-sdlc-build-planning \
+  --code my-build-planning \
+  --name "My Build Planning Project"
+```
+
+상태 조회:
+
+```bash
+npx agentic project status --code my-build-planning
+npx agentic project status --code my-build-planning --format json
+```
+
+## 문서 구분
+
+패키지 사용자는 필요한 문서만 보면 됩니다.
+
+공통 패키지 개발 기준은 구축 저장소의 `docs/standards/package-development-standard.md`를 따릅니다.
+
+| 대상 | 문서 | 내용 |
+| --- | --- | --- |
+| 운영환경 사용자 | [docs/usage.md](./docs/usage.md) | 설치, 실행 확인, 기본 사용법 |
+| 운영환경 사용자 | [docs/configuration.md](./docs/configuration.md) | 외부 실행 프로젝트의 환경 설정 원칙 |
+| 운영환경 담당자 | [docs/operations.md](./docs/operations.md) | 운영환경 설치, 검증, 장애 확인 |
+| 구축 담당자 | [docs/build.md](./docs/build.md) | 개발, 빌드, 로컬 검증 |
+| 구축 담당자 | [docs/publishing.md](./docs/publishing.md) | npm pack, publish, publish 검증 |
+| 구축 담당자 | [docs/delivery.md](./docs/delivery.md) | 구축 환경에서 운영환경으로 전달할 패키지별 기준 |
+| 구축 담당자 | [docs/schema/generated/README.md](./docs/schema/generated/README.md) | `tbls`가 생성한 SQLite 테이블 설계 문서 |
+| 구축 담당자 | [docs/schema/generated/schema.svg](./docs/schema/generated/schema.svg) | `tbls`가 생성한 SQLite 테이블 가시화 다이어그램 |
+| 구축 담당자 | [docs/schema/migrations.md](./docs/schema/migrations.md) | SQLite migration 적용 순서와 의도 |
+
+## 환경 정보 제공 원칙
+
+`@soddong/agentic-runtime`은 환경 정보를 직접 소유하지 않습니다.
+
+registry, 인증, 네트워크, 중앙 DBMS, Agent profile 같은 환경 정보는 이 패키지를 설치해서 사용하는 외부 실행 프로젝트가 제공합니다.
+
+```text
+@soddong/agentic-runtime
+  - 환경 정보의 형식과 로딩 규칙을 정의
+  - package 내부에 특정 환경 값을 고정하지 않음
+
+consumer project
+  - .npmrc
+  - .env
+  - agentic.config.*
+  - CI/CD variables
+  - network/profile 설정
+```
+
+## 역할
+
+```text
+@soddong/agentic-runtime
+  - CLI entrypoint
+  - package/module registry
+  - module composition
+  - lifecycle execution
+  - Codex adapter bootstrap
+  - SQLite migration composition
+  - execution project scaffold
+  - runtime context
+```
+
+`@soddong/agentic-runtime`은 Agentic Platform 전체가 아닙니다. Agentic Platform은 전체 제품/체계명이고, `@soddong/agentic-runtime`은 로컬 실행 기반 패키지입니다.
+
+## MVP 범위
+
+초기 `@soddong/agentic-runtime`의 범위는 의도적으로 작게 유지합니다.
+
+```text
+1. workspace/package skeleton
+2. local CLI entrypoint
+3. project-local SQLite initialization
+4. package migration composition
+5. module registry
+6. execution project scaffold
+```
+
+다음 항목은 초기 runtime 패키지 범위에 포함하지 않습니다.
+
+```text
+- full workflow engine
+- PostgreSQL sync implementation
+- multi-agent orchestration
+- web UI
+- DOCX/PPTX/PDF rendering
+```