@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/tutorial, agentic agent register/context | | 예정 명령 | agentic validate, agentic render |

Agent 실행 API

Agent module은 AgentRuntimeClient 형태로 run()을 제공하고, 실행 프로젝트 또는 router는 runAgentRuntimeClient()로 실행합니다.

이 방식에서 Agent는 실제 업무 로직만 담당하고, @soddong/agentic-runtime은 실행 이력, 사용자 지시, 로그, 결과 저장을 표준화합니다.

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을 수행합니다.

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을 등록합니다.

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를 조립하려면 다음 명령을 사용합니다.

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입니다.

npm install @soddong/[email protected]

사용자 ~/.npmrc에 별도 registry가 남아 있으면 공식 registry를 명시하거나 user config를 정리합니다.

npm config set registry https://registry.npmjs.org/ --location=user
npm install @soddong/[email protected] --registry=https://registry.npmjs.org/

publish 권한이 필요한 사용자는 ~/.npmrc에 npm token을 설정합니다. token 실값은 문서, source, CI log에 기록하지 않습니다.

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

실행 확인

npx agentic --version
npx agentic --help

기대 결과:

@soddong/agentic-runtime 0.17.18

프로젝트 초기화

사용자 프로젝트에서 다음 명령을 실행하면 기본 설정 파일과 로컬 작업 디렉터리를 생성합니다.

npx agentic init

생성 구조:

consumer-project/
  agentic.config.json
  .gitignore
  .agentic/
    AGENTS.md
    README.md
    bin/
      agentic-hook.mjs
    data/
    logs/
      modules/

agentic init, agentic setup, agentic bundle apply, agentic adapter install 경로는 .gitignore managed block을 생성하거나 갱신합니다. 기본 제외 대상은 node_modules/, dist/, *.tsbuildinfo, *.tgz 같은 npm/TypeScript local artifact와 .agentic/, .agents/, plugins/agentic-runtime-codex/ 같은 Agentic runtime local state입니다. agentic.config.json, package.json, package-lock.json, seed source, scripts는 일반적으로 Git에 포함합니다.

Git repository를 clone한 사용자는 의존성 설치 후 runtime local state와 hook wrapper를 다시 생성합니다.

npm install
npx agentic setup --adapter codex --force

이 과정에서 .agentic/bin/agentic-hook.mjs는 현재 프로젝트의 node_modules/@soddong/agentic-runtime을 사용하도록 갱신됩니다. 다른 사용자 환경의 npx 임시 경로나 절대 경로가 들어간 stale hook wrapper는 Git에 포함하지 않습니다.

설치된 패키지 문서 위치와 현재 프로젝트 설정 상태는 다음 명령으로 확인합니다.

npx agentic docs
npx agentic config

Codex, Kiro, Claude Code adapter까지 함께 준비하려면 통합 setup 명령을 사용합니다.

npx agentic setup --adapter codex
npx agentic setup --adapter kiro
npx agentic setup --adapter claude-code

adapter install을 먼저 실행해도 됩니다. 프로젝트가 아직 초기화되지 않았으면 adapter install이 내부에서 init과 db init을 먼저 수행한 뒤 adapter 설치까지 진행합니다.

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만 갱신합니다.

<!-- agentic-runtime:start version=0.17.18 -->
...
<!-- agentic-runtime:end -->

사용자가 직접 작성한 지침은 managed block 밖에 둡니다.

Agent hook은 성능을 위해 npx를 매번 호출하지 않고 project-local wrapper를 사용합니다.

node .agentic/bin/agentic-hook.mjs --source kiro --event PromptSubmit

파일만 생성하고 Codex CLI marketplace/plugin add는 건너뛰려면 다음을 사용합니다.

npx agentic setup --adapter codex --prepare-only

Runtime Execution 기록

사용자 지시를 runtime execution으로 기록합니다.

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 이력 조회

저장된 사용자 지시, 실행 상태, 로그, 결과는 다음 명령으로 조회합니다.

npx agentic execution list --range today
npx agentic execution latest
npx agentic execution show <run-id>
npx agentic execution summary --range 7d

Agent나 자동화 도구가 사용하기 쉬운 JSON 출력도 지원합니다.

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를 사용합니다.

주요 조회 옵션:

--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가 있는 프로젝트에서만 수행합니다.

설치:

npx agentic adapter install codex

상태 확인:

npx agentic adapter status codex

이미 설치된 Codex adapter 파일을 현재 @soddong/agentic-runtime 버전 기준으로 갱신하려면 --force를 사용합니다.

npx agentic adapter install codex --force
codex plugin list

생성 구조:

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/bin/agentic-hook.mjs는 사용자 환경에서 재생성되는 파일입니다. Git에 포함된 오래된 wrapper가 다른 사용자의 npx 임시 경로를 가리키면 Codex Stop hook이 import 단계에서 실패할 수 있으므로, .agentic/는 Git에서 제외하고 clone 후 npx agentic setup --adapter codex --force로 재생성합니다.

같은 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 호환용 보조 파일 |

설치:

npx agentic adapter install kiro

상태 확인:

npx agentic adapter status kiro

이미 생성된 Kiro adapter 파일을 현재 @soddong/agentic-runtime 버전 기준으로 갱신하려면 --force를 사용합니다.

npx agentic adapter install kiro --force

Kiro CLI V2에서 hook agent를 기본값으로 지정하려면 --set-default를 명시합니다. 이 옵션은 사용자 Kiro 설정을 변경할 수 있으므로 기본 설치에서는 실행하지 않습니다.

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입니다.

직접 확인:

kiro-cli agent set-default kiro_with_hooks
kiro-cli --agent kiro_with_hooks

생성 구조:

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을 적용하려면 다음 중 하나로 실행합니다.

kiro-cli --agent kiro_with_hooks
kiro-cli agent set-default kiro_with_hooks

상세한 Kiro CLI/IDE hook 설명은 consumer 프로젝트에 생성되는 다음 파일을 확인합니다.

cat plugins/agentic-runtime-kiro/hooks/kiro-hook-guide.md

검증:

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에 기록합니다.

설치:

npx agentic adapter install claude-code

상태 확인:

npx agentic adapter status claude-code

이미 생성된 Claude Code adapter 파일을 현재 @soddong/agentic-runtime 버전 기준으로 갱신하려면 --force를 사용합니다.

npx agentic adapter install claude-code --force

생성/수정 구조:

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를 초기화합니다.

npx agentic db init
npx agentic db status

기본 DB 파일:

.agentic/platform.sqlite

Module Registry

실행 프로젝트에서 사용할 Agentic package는 프로젝트 DB에 명시적으로 등록합니다.

npx agentic module register sample-agent-package 0.0.1 application
npx agentic module list

module layer 값:

runtime
domain
capability
application
support

Methodology Project Create

projectCreation.mode=SINGLE_PROJECT인 methodology Bundle을 적용하고 단일 execution project까지 생성하려면 다음 명령을 사용합니다.

npx agentic project create @example/single-project-methodology

projectCreation이 없는 기존 Bundle도 호환을 위해 SINGLE_PROJECT로 해석합니다. SCAFFOLDING_PROFILE Bundle은 provider가 선언한 npm bin entrypoint를 사용해야 하며 generic project create는 package manifest 사전검사 후 대상 프로젝트를 변경하지 않고 BUNDLE.SCAFFOLDING_ENTRYPOINT_REQUIRED로 종료합니다. entrypoint는 안내용 식별자이며 Runtime이 실행하지 않습니다.

미설치 Bundle의 사전검사용 임시 설치에는 --ignore-scripts를 적용하며 실제 Bundle 설치의 lifecycle 정책은 변경하지 않습니다. Scaffolding 경로 보안 계약은 symlink나 Windows junction 자체를 금지하는 것이 아니라 realpath 기준 trusted workspace root 이탈을 차단하는 것입니다. trusted root 내부로 수렴하는 링크는 허용합니다. Binding fingerprint의 set 성격 문자열은 JavaScript UTF-16 code unit ordinal 순서로 정렬하며 locale 기반 비교를 사용하지 않습니다.

runtime을 프로젝트에 미리 설치하지 않고 바로 실행하려면 다음 명령을 사용합니다.

npx --yes --loglevel=error -p @soddong/agentic-runtime@<version> agentic project create @example/single-project-methodology

--loglevel=error는 npm 설치 과정의 일반 warning 로그를 숨깁니다. 0.17.6부터 runtime은 Node 내장 node:sqlite를 사용하므로 better-sqlite3 native addon 설치가 필요 없습니다. 오류가 발생하면 error 로그는 그대로 표시됩니다.

이 명령은 다음 단계를 자동으로 수행합니다.

- npm project package.json 보장
- project runtime init/db init 보장
- methodology seed bundle provider package npm install
- default bundle 탐색
- bundle manifest의 requires.packages npm install
- required package 자동 module register
- seed import
- seed apply
- default execution project 생성
- `.agentic/reports/<project-code>.html` HTML report 생성
- `.agentic/reports/<project-code>-tutorial.html` methodology tutorial HTML 생성

성공하면 마지막에 HTML report 경로와 methodology tutorial 생성 상태가 출력됩니다. HTML report는 execution project의 현재 상태와 Activity별 산출물 표준을 표시합니다. Methodology tutorial은 runtime DB에 적재된 방법론 정의를 기준으로 Stage/Activity/Task/Step 구조를 사용자 친화적으로 탐색할 수 있게 제공합니다. 방법론 domain table이 아직 없으면 tutorial은 생성되지 않고 skipped 사유가 표시됩니다.

산출물 표준 탭은 다음 구성을 기본으로 합니다.

개요 / 개념 / 서식 / 작성 기준 / 예시 / 검증 기준

methodology seed manifest가 reportProfile을 제공하면 report title, subtitle, navigation label, activity 상세 label, 빈 산출물 안내 문구, seed metadata 표시 여부를 bundle 기준으로 조정합니다. reportProfile이 없으면 runtime 기본 viewer 설정을 사용합니다.

이미 생성된 execution project에서 methodology tutorial만 다시 생성하려면 다음 명령을 사용합니다.

npx agentic project tutorial --code my-build-planning
npx agentic project tutorial --code my-build-planning --output .agentic/reports/my-tutorial.html

project tutorial은 execution project code와 runtime DB의 methodology domain table을 함께 확인합니다. methodology_methodologies, methodology_stages, methodology_activities, methodology_steps 등이 없으면 project create <methodology-package> 또는 bundle apply --install-required로 seed 적용 상태를 먼저 확인합니다.

Execution Tutorial Mode

방법론 학습, Activity/Task/Step 확인, 산출물 표준 확인만 필요하면 설치된 methodology seed package를 읽는 tutorial mode를 사용합니다.

npx --yes -p @soddong/[email protected] agentic tutorial open \
  @soddong/[email protected] \
  --port 4791

tutorial open은 다음만 수행합니다.

- methodology seed package 설치 또는 확인
- Workbench package 설치 또는 확인
- 설치된 seed package root를 Workbench에 전달
- 현재 작업 디렉터리를 execution project root로 유지
- Workbench를 read-only tutorial mode로 실행

이 명령은 .agentic/platform.sqlite를 생성하거나 갱신하지 않습니다. 방법론 tree와 산출물 표준은 seed package에서 읽습니다. 단, Workbench의 기준 정보 조회 화면은 seed package에 configuration seed JSON이 없을 때 현재 execution project root의 .agentic/platform.sqlite에 있는 configuration_* table을 read-only fallback으로 조회할 수 있습니다. 실행 상태, 로그, 산출물 생성 상태를 확인하는 Execution View는 별도 DB 기반 기능입니다.

필요한 경우에만 기본값을 override합니다.

npx agentic project create @example/single-project-methodology \
  --bundle ai-agent-sdlc-build-planning \
  --code my-build-planning \
  --name "My Build Planning Project"

methodology package 버전을 고정하려면 package 인자에 npm version spec을 붙입니다.

npx --yes --loglevel=error -p @soddong/agentic-runtime@<version> agentic project create @example/single-project-methodology@<version>

Codex 기반으로 execution 이력을 기록하려면 project 생성 후 adapter setup을 추가로 실행합니다.

npx --yes -p @soddong/[email protected] agentic setup --adapter codex --force

Project Bundle Registry

methodology seed bundle provider package가 설치되어 있으면 runtime에 bundle 설치 상태를 등록할 수 있습니다.

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는 project create <methodology-package>보다 낮은 수준의 멱등적 상태 수렴 명령이며, 신규 설치와 업데이트에서 다음 단계를 한 번에 수행합니다.

- 프로젝트 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

등록된 required package가 `applyAgenticMigrations`를 제공하면 seed apply 전에 모듈 소유 pending migration을 적용합니다. Runtime은 SQL을 소유하지 않고 hook 실행만 조정합니다. Bundle provider package version, Bundle version, 실제 Bundle content SHA-256이 마지막 성공 apply와 모두 같으면 seed apply를 생략하고 `up_to_date`로 종료합니다.

기본 bundle apply는 npm package를 자동 설치하지 않고, 이미 설치된 package만 등록/적용합니다. 사용자 편의 설치까지 포함하려면 --install-required를 사용합니다.

npx agentic bundle apply @soddong/agentic-methodology-ai-agent-sdlc \
  --bundle ai-agent-sdlc-build-planning \
  --install-required

bundle provider package 버전을 고정해야 하면 동일하게 package 인자에 npm version spec을 붙입니다.

npx agentic bundle apply @soddong/[email protected] \
  --bundle ai-agent-sdlc-build-planning \
  --install-required

Local directory, tarball 또는 Npx cache의 물리 source를 사용해야 할 때는 bundle apply <source-spec> --dependency-spec <package-name@exact-version> --install-required로 source locator와 consumer dependency identity를 분리합니다. Runtime은 현재 payload를 source에서 설치하되 package.json과 lockfile에는 exact version만 남깁니다. 의도적인 local development dependency는 --allow-local-dependency를 명시해야 합니다.

수동 설치를 선호하면 다음처럼 먼저 packages를 설치한 뒤 bundle apply를 실행할 수 있습니다.

npm install @soddong/agentic-methodology-ai-agent-sdlc @soddong/agentic-domain-methodology @soddong/agentic-domain-configuration @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으로 생성합니다.

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을 저장합니다. methodology bundle의 methodology, identityRules, lifecycle, phases, processes, stages, activities, tasks, steps, activityArtifactRequirements, criteria, handoffs section은 @soddong/agentic-domain-methodology target item으로 계획됩니다. configurationCodeGroups, configurationCodes, configurationIdentityRules, configurationItemTypes, configurationItems, configurationItemRelations, configurationBaselines section은 @soddong/agentic-domain-configuration target item으로 계획됩니다. identityRules는 방법론 요소별 managed ID formatter rule이며, 요소 seed의 managedId, identityNo, stageAbbr, shortCode, managedArtifactId 저장값 검증 기준으로 사용됩니다. tasks는 activityCode + taskCode, steps는 activityCode + taskCode + stepCode를 기준으로 대상이 명확해지는 구조를 권장합니다. target package가 설치 또는 등록되지 않았으면 해당 item은 blocked로 표시합니다.

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로 남습니다.

setup --adapter codex만 실행한 뒤 methodology_*, configuration_*, artifact_standard_*, validation_contract_* 같은 domain table 또는 방법론 데이터가 보이지 않는 것은 정상입니다. 해당 데이터는 project create <methodology-package> 또는 bundle apply --install-required가 target package 설치/등록과 seed apply를 수행할 때 생성됩니다.

후속 갱신 기준

최초 생성 이후 방법론 seed bundle 또는 required package를 갱신할 때는 project create를 다시 실행하지 않고 bundle apply를 사용합니다.

npm install @soddong/agentic-methodology-ai-agent-sdlc@<new-version>

npx --yes -p @soddong/[email protected] agentic bundle apply \
  @soddong/agentic-methodology-ai-agent-sdlc@<new-version> \
  --bundle ai-agent-sdlc-build-planning \
  --install-required

Codex hook wrapper, plugin bridge, local adapter 설정을 갱신하려면 adapter setup을 별도로 실행합니다.

npx --yes -p @soddong/[email protected] agentic setup --adapter codex --force

현재 runtime CLI는 동일 execution project를 in-place로 갱신하는 project update 명령을 제공하지 않습니다. 동일 projectCode로 project create를 재실행하면 기존 execution project가 존재하므로 실패합니다. 갱신된 bundle 기준의 snapshot을 새로 만들려면 새 projectCode를 지정합니다.

npx --yes -p @soddong/[email protected] agentic project create \
  --bundle ai-agent-sdlc-build-planning \
  --code ai-agent-sdlc-build-planning-v2 \
  --name "AI-Agent SDLC Build Planning v2"

Execution Project Lifecycle

seed apply가 성공한 bundle은 execution project로 생성할 수 있습니다. 1차 범위의 execution project는 workflow engine이 아니라, bundle의 stage/activity/task/step과 primary output artifact 기준을 runtime DB에 snapshot으로 등록하는 lifecycle scaffold입니다.

일반 consumer는 앞의 project create <methodology-package> 명령을 사용하면 됩니다. 이미 bundle을 수동으로 적용한 경우에는 아래 low-level 명령을 사용할 수 있습니다.

npx agentic project create \
  --bundle ai-agent-sdlc-build-planning \
  --code my-build-planning \
  --name "My Build Planning Project"

상태 조회:

npx agentic project status --code my-build-planning
npx agentic project status --code my-build-planning --format json

Configuration Item 기반 프로젝트 스캐폴딩 API

Runtime은 방법론 비종속 공통 API로 validateProjectScaffoldingProfile, planProjectScaffolding, createExecutionProjectsFromBundle, materializeProjectScaffolding, verifyProjectScaffolding을 제공합니다.

• 방법론 Bundle은 Viewpoint, Project Scope/Execution Unit Type, Execution Project code/name template, 부모 참조 Directory Tree와 프로젝트 데이터 소스 설명을 ProjectScaffoldingProfile로 제공한다.
• validateProjectScaffoldingProfile은 외부 JSON을 구조화 issue로 검증한다.
• planProjectScaffolding은 baseline membership, 직계 Execution Unit, 방법론 Phase/Stage/Activity 참조, project code 충돌 및 Directory Tree를 파일 생성 전에 검증한다.
• createExecutionProjectsFromBundle은 Execution Unit별 Runtime Execution Project snapshot을 하나의 SQLite transaction으로 생성한다.
• materializeProjectScaffolding은 staging 설정 교체와 실패 보상 처리를 사용해 project-config/ 및 실행 지원 빈 디렉터리를 생성한다. 기존 실행 파일은 삭제하지 않는다.
• verifyProjectScaffolding은 Runtime DB를 read-only로 열어 계획된 Execution Project 존재와 이름을 확인한다.
• Runtime 공통 API는 SSF, L2/L2.5, 특정 방법론 코드나 외부 데이터 설치 도구를 알지 않는다.
• 외부 데이터 소스는 위치와 접근 정책만 기록하며 데이터를 내려받거나 복사하지 않는다.

물리 프로젝트 하나는 로컬 .agentic/platform.sqlite 하나를 사용하고 각 Execution Unit은 독립 Runtime Execution Project snapshot을 가집니다. 실행 상태 정본은 DB에 유지하며 물리 폴더와 Configuration Item 범위의 연결은 project-config/execution-project-binding.json에 기록합니다. 기존 Stage/Activity/Task/Step 고유성이 Execution Project 범위이므로 DB migration은 추가하지 않습니다.

문서 구분

패키지 사용자는 필요한 문서만 보면 됩니다.

공통 패키지 개발 기준은 구축 저장소의 docs/standards/package-development-standard.md를 따릅니다.

| 대상 | 문서 | 내용 | | --- | --- | --- | | 운영환경 사용자 | docs/usage.md | 설치, 실행 확인, 기본 사용법 | | 운영환경 사용자 | docs/configuration.md | 외부 실행 프로젝트의 환경 설정 원칙 | | 운영환경 담당자 | docs/operations.md | 운영환경 설치, 검증, 장애 확인 | | 구축 담당자 | docs/build.md | 개발, 빌드, 로컬 검증 | | 구축 담당자 | docs/publishing.md | npm pack, publish, publish 검증 | | 구축 담당자 | docs/delivery.md | 구축 환경에서 운영환경으로 전달할 패키지별 기준 | | 구축 담당자 | docs/schema/generated/README.md | tbls가 생성한 SQLite 테이블 설계 문서 | | 구축 담당자 | docs/schema/generated/schema.svg | tbls가 생성한 SQLite 테이블 가시화 다이어그램 | | 구축 담당자 | docs/schema/migrations.md | SQLite migration 적용 순서와 의도 |

환경 정보 제공 원칙

@soddong/agentic-runtime은 환경 정보를 직접 소유하지 않습니다.

registry, 인증, 네트워크, 중앙 DBMS, Agent profile 같은 환경 정보는 이 패키지를 설치해서 사용하는 외부 실행 프로젝트가 제공합니다.

@soddong/agentic-runtime
  - 환경 정보의 형식과 로딩 규칙을 정의
  - package 내부에 특정 환경 값을 고정하지 않음

consumer project
  - .npmrc
  - .env
  - agentic.config.*
  - CI/CD variables
  - network/profile 설정

역할

@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의 범위는 의도적으로 작게 유지합니다.

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 패키지 범위에 포함하지 않습니다.

- full workflow engine
- PostgreSQL sync implementation
- multi-agent orchestration
- web UI
- DOCX/PPTX/PDF rendering