@soddong/agentic-application-methodology-workbench

@soddong/agentic-application-methodology-workbench는 methodology seed bundle project가 사용하는 reusable authoring workbench application package다.

Platform은 Workbench server, UI shell, config contract를 제공한다. 개별 Bundle/Seed project는 ui/workbench.config.json, seed files, UI planning docs, scenario/step asset/sample directories를 제공한다.

Run

Published package를 사용하는 consumer project에서는 다음과 같이 설치한다.

npm install @soddong/[email protected]

workspace에서 개발 중인 경우에는 다음 명령을 사용한다.

npm run build -w @soddong/agentic-application-methodology-workbench
npx --no-install agentic-methodology-workbench --project /path/to/methodology-seed-project

Execution project에서 설치된 seed package를 read-only 조회용으로 실행할 때는 execution mode를 명시한다.

npx --no-install agentic-methodology-workbench \
  --project ./node_modules/@soddong/agentic-methodology-ai-agent-sdlc \
  --experience-mode execution

Execution mode에서 --project가 현재 실행 project가 아니라 methodology seed package root를 가리키면, Workbench는 현재 작업 디렉터리를 execution project root로 보고 .agentic/platform.sqlite의 configuration 기준정보를 조회한다. 다른 execution project DB를 명시하려면 다음 옵션을 사용한다.

npx --no-install agentic-methodology-workbench \
  --project ./node_modules/@soddong/agentic-methodology-ai-agent-sdlc \
  --experience-mode execution \
  --execution-project-root /path/to/execution-project

기본 URL은 다음과 같다.

http://127.0.0.1:4783

--project는 ui/workbench.config.json을 가진 Bundle/Seed project root여야 한다. Platform repository root에서 실행하면 package fallback config가 적용되어 실제 방법론 tree와 산출물 표준이 비어 보일 수 있다.

Config

Workbench는 대상 project의 다음 파일을 읽는다.

ui/workbench.config.json

schema는 schemas/workbench-config.schema.json에 둔다.

Methodology Hierarchy

Workbench가 표시하고 authoring하는 방법론 표준 계층은 다음과 같다.

Lifecycle 생애주기
  -> Phase 페이즈
    -> Process 프로세스
      -> Stage 단계
        -> Activity 활동
          -> Task 작업
            -> Step 절차

Phase는 페이즈, Stage는 단계로 표기해 두 계층의 의미를 분리한다.

Landing And Phase Tabs

Workbench의 첫 화면은 대상 Bundle/Seed project의 lifecycle.json, phases.json, processes.json를 기준으로 lifecycle model overview를 표시한다. lifecycle.json은 하위 호환을 위해 단일 객체와 배열을 모두 지원한다. 배열인 경우 Workbench는 공식 lifecycle model과 임시 authoring/rehearsal lifecycle model을 함께 표시하고, 각 lifecycle의 phaseCodes가 지정되어 있으면 해당 Phase만 진입 대상으로 사용한다. Bundle/Seed authoring 환경에서는 lifecycle card에서 Authoring 또는 Tutorial 진입 모드를 선택한 뒤 Workbench shell로 들어간다. Execution project에서는 선택지를 노출하지 않고 read-only Tutorial로 진입한다.

Landing page는 lifecycle card의 프로세스 맵 control로 선택한 lifecycle의 Phase, Process, Stage, Activity 흐름을 modal overlay에서 조망할 수 있다. Process map은 단순 목록이 아니라 SVG infographic으로 표시하며, Phase swimlane, Process route band, Stage grouping container, Activity sequence node, 실행 산출물 표준 연결을 한 화면에 표시한다. 산출물 맵 control은 같은 lifecycle 범위에서 Activity primary output과 Artifact Standard coverage를 한 화면에 표시한다. Landing header의 구성 요소 보기 control은 선택한 lifecycle 데이터와 무관한 정적 메타모델 infographic이다. 이 화면은 methodology-structure-infographic.png 단일 PNG 자산으로 계층 구조 및 포함 관계, 구성요소 | 개념 | 역할 | 관계 표, 관계 요약을 함께 표시한다. 세 modal은 검토용 overlay이며, Workbench shell 진입 흐름은 기존 lifecycle card의 Authoring 또는 Tutorial control을 유지한다.

Workbench shell의 좌측 tree 패널 상단은 고정 Process 제목이 아니라 Phase tab으로 표시한다. Phase tab 선택 시 /api/workbench/phases/:phaseCode를 다시 로딩하고 해당 Phase의 Stage, Activity, Task, Step tree를 표시한다. 선택한 lifecycle, Phase, 진입 mode는 URL hash에 보존되며 브라우저 새로고침 후에도 같은 상세 화면과 mode로 복원된다. shell header의 목록 control은 lifecycle landing page로 돌아가는 explicit navigation이다.

산출물 viewer의 전체 폭 option은 좌측 navigation panel을 접고 artifact canvas의 outer padding을 줄여 표 중심 산출물의 가로 공간을 확보한다.

Workbench Modes

Authoring과 Tutorial은 별도 UI가 아니라 하나의 Workbench shell이 진입 시점에 선택하는 표시 모드다.

| Mode | 대상 | 동작 | | --- | --- | --- | | Authoring | Bundle/Seed 작성자 | Task/Step 구조, 산출물 표준, 선택 Step editor detail을 함께 표시한다. | | Tutorial | Execution 또는 조회 사용자 | 동일한 tree와 산출물 표준을 read-only로 표시하고 Step editor detail은 숨긴다. |

Execution project에서 사용하는 경우 config 또는 CLI의 --experience-mode execution으로 Tutorial read-only 경험을 기본값으로 둔다. Bundle/Seed authoring config는 authoring을 사용하며, 상세 화면 내부에서는 mode 전환 버튼을 제공하지 않고 현재 mode indicator만 표시한다.

UI Design System

Workbench UI 변경은 Design Tokens -> Component Rules -> Workbench Layout Rules 순서로 검토한다. 색상, spacing, radius, shadow, typography, landing lifecycle card, Stage flow, Activity popup, methodology tree, artifact viewer, mode indicator 기준은 docs/ui-design-system.md를 따른다.

Task Step Authoring Source

Task의 Step 정의 원천은 methodology-authoring/tasks/{taskCode}/steps/{stepCode} 아래에 둔다. seed steps.json은 배포용 materialized 결과로 보고, Workbench draft/apply workflow를 통해 반영한다.

npx --no-install agentic-methodology-workbench scaffold-task-source \
  --project /path/to/methodology-seed-project \
  --task <task-code>

ViewModels And Authoring Drafts

Workbench는 대상 project의 seed JSON을 읽어 ViewModel API를 제공한다. Authoring 변경은 먼저 methodology-authoring/drafts 또는 config의 authoringSources.draftsRoot 아래에 draft JSON으로 저장한다. 원본 seed 반영은 검증된 draft에 대해 명시적인 apply action으로만 수행한다.

Execution mode의 Configuration 조회는 execution DB를 기준 원천으로 사용한다. Summary API는 Item과 baseline item reference 전문을 전송하지 않고 유형별 집계와 기준선별 집계만 반환한다. 목록은 선택한 Viewpoint, Viewpoint Version, Baseline, Item Type을 SQL 조건으로 적용하고 LIMIT/OFFSET으로 조회한다. 계층과 상세 조회도 각각 기준선·부모 조건 및 Item UUID 단건 SQL을 사용한다. 이 계약은 승인된 과거 기준선과 최신 기준선이 함께 있는 DB에서도 전체 데이터를 메모리에 적재하지 않기 위한 운영 기준이다.

| Endpoint | ViewModel | | --- | --- | | /api/workbench/lifecycle | LifecycleOverviewVM | | /api/workbench/phases | PhaseDetailVM | | /api/workbench/activities | ActivityWorkbenchVM | | /api/workbench/activities/:activityCode/authoring | ActivityAuthoringVM | | /api/workbench/artifacts | ArtifactStandardVM | | /api/workbench/governance | GovernanceVM |

| Endpoint | Method | 목적 | | --- | --- | --- | | /api/workbench/authoring/steps/:stepCode/draft | PUT | Step title, execution mode, instruction, script path draft 저장 | | /api/workbench/authoring/steps/:stepCode/apply-plan | GET | Step draft를 seed에 반영할 때의 변경 필드 preview | | /api/workbench/authoring/steps/:stepCode/apply | POST | 검증된 Step draft를 seed steps.json에 반영 | | /api/workbench/authoring/tasks/:taskCode/draft | PUT | Task-level authoring draft 저장 |

Verification

개발 중에는 실제 Bundle/Seed project를 대상으로 build, typecheck, smoke test를 함께 수행한다.

npm run build -w @soddong/agentic-application-methodology-workbench
npm run typecheck -w @soddong/agentic-application-methodology-workbench
npm run smoke -w @soddong/agentic-application-methodology-workbench -- --project /path/to/methodology-seed-project

smoke test는 API/ViewModel, HTML shell, CSS/JS 계약을 확인한다. 브라우저 시각 품질은 별도 화면 검수로 확인한다.

public npm publish 후에는 깨끗한 consumer project에서 registry install, package import, CLI boot, health API를 확인한다.

npm install @soddong/[email protected]
node -e "import('@soddong/agentic-application-methodology-workbench').then((m)=>console.log(m.methodologyWorkbenchPackage.version))"
npx agentic-methodology-workbench --project /path/to/methodology-seed-project
curl -sS http://127.0.0.1:4783/api/health

Responsibility Boundary

| 구분 | 담당 | | --- | --- | | reusable workbench UI/server/config contract | 본 패키지 | | methodology-specific seed/config/scenario/sample | methodology bundle project | | runtime DB, run, log, output | @soddong/agentic-runtime | | methodology definition DB/API | @soddong/agentic-domain-methodology | | artifact standard DB/API | @soddong/agentic-domain-artifact-standard |