@soddong/agentic-application-methodology-workbench 0.1.0

package/docs/configuration.md

@@ -0,0 +1,65 @@
+# Configuration
+
+## Project Config
+
+대상 Bundle/Seed project는 다음 config를 제공한다.
+
+```text
+ui/workbench.config.json
+```
+
+최소 예시는 다음과 같다.
+
+```json
+{
+  "schemaVersion": "0.1",
+  "workbenchId": "ai-agent-sdlc-build-planning",
+  "title": "AI-Agent SDLC Build Planning Workbench",
+  "experienceMode": "authoring",
+  "methodologyPackageName": "@soddong/agentic-methodology-ai-agent-sdlc",
+  "bundleCode": "ai-agent-sdlc-build-planning",
+  "seedRoot": "seeds/ai-agent-sdlc-build-planning",
+  "uiPlanningRoot": "ui/planning",
+  "authoringSources": {
+    "scenariosRoot": "methodology-authoring/scenarios",
+    "tasksRoot": "methodology-authoring/tasks",
+    "stepAssetsRoot": "methodology-authoring/step-assets",
+    "artifactSamplesRoot": "methodology-authoring/artifact-samples",
+    "draftsRoot": "methodology-authoring/drafts",
+    "generatedDocsRoot": "docs/generated/ai-agent-sdlc-build-planning",
+    "generatedOutputsRoot": "outputs/methodology-workbench/generated-artifacts"
+  }
+}
+```
+
+`experienceMode`는 `authoring` 또는 `execution`을 사용한다. 생략 시 하위 호환을 위해 `authoring`으로 동작하지만, 신규 config에는 명시하는 것을 권고한다.
+
+| Mode | 권장 사용 위치 | 의미 |
+| --- | --- | --- |
+| `authoring` | Bundle/Seed project | Authoring과 Tutorial 전환을 허용하고 Step editor detail을 표시할 수 있다. |
+| `execution` | Execution project | Tutorial read-only 경험으로 고정하고 authoring 전환 UI를 표시하지 않는다. |
+
+`authoringSources.tasksRoot`가 생략되면 Workbench는 `methodology-authoring/tasks`를 기본 Task/Step authoring source 위치로 사용한다.
+
+`authoringSources.draftsRoot`가 생략되면 Workbench는 `methodology-authoring/drafts`를 기본 draft 저장 위치로 사용한다.
+
+`authoringSources.generatedDocsRoot`가 생략되면 Workbench는 `docs/generated/{bundleCode}`를 기본 산출물 표준 Markdown projection 위치로 사용한다. 산출물 표준 패널은 이 경로의 `artifact-standards/{artifactStandardCode}/template.document.md`, `sample.document.md`, `format.metadata.md`와 공통 개념 문서를 HTML로 렌더링한다.
+
+## Seed Data Used By UI
+
+Landing page와 Phase tab은 별도 UI 전용 데이터를 만들지 않고 Bundle/Seed project의 seed JSON을 기준으로 렌더링한다.
+
+| Seed file | UI 사용 |
+| --- | --- |
+| `lifecycle.json` | Landing page의 lifecycle model card |
+| `phases.json` | Landing page의 Phase 요약과 Workbench shell Phase tab |
+| `processes.json` | Phase와 Stage를 연결하는 Process mapping |
+| `stages.json`, `activities.json`, `tasks.json`, `steps.json` | 선택된 Phase의 tree |
+
+## CLI Options
+
+| Option | 기본값 | 설명 |
+| --- | --- | --- |
+| `--project` | 현재 작업 디렉터리 | Workbench 대상 Bundle/Seed project root |
+| `--host` | `127.0.0.1` | local server bind host |
+| `--port` | `4783` | local server port |

package/docs/delivery.md

@@ -0,0 +1,15 @@
+# Delivery
+
+Delivery 단위는 reusable application package다.
+
+Bundle/Seed project에는 Workbench package 자체를 복사하지 않고, config와 authoring source만 둔다.
+
+## Delivery Checklist
+
+| 항목 | 기준 |
+| --- | --- |
+| package build | `npm run build -w @soddong/agentic-application-methodology-workbench` 성공 |
+| typecheck | `npm run typecheck -w @soddong/agentic-application-methodology-workbench` 성공 |
+| seed project smoke | 실제 Bundle/Seed project root를 대상으로 `npm run smoke` 성공 |
+| mode contract | Bundle/Seed는 `authoring`, Execution project는 `execution` read-only 기준을 따른다. |
+| responsibility boundary | package에는 reusable UI/server/config contract만 포함하고 방법론별 seed/source는 Bundle/Seed project에 둔다. |

package/docs/operations.md

@@ -0,0 +1,28 @@
+# Operations
+
+## Start
+
+```bash
+npx --no-install agentic-methodology-workbench --project <seed-project-root>
+```
+
+`<seed-project-root>`는 `ui/workbench.config.json`을 가진 Bundle/Seed project root여야 한다. Platform repository root에서 실행하면 Workbench package fallback config가 적용되어 실제 방법론 tree가 비어 보일 수 있다.
+
+## Health Check
+
+```bash
+curl -sS http://127.0.0.1:4783/api/health
+```
+
+## UI Flow
+
+브라우저에서 Workbench를 열면 먼저 lifecycle model landing page가 표시된다. lifecycle model을 선택하면 Workbench shell로 진입하고, 좌측 tree 패널 상단의 Phase tab으로 Phase를 전환한다.
+
+## Smoke Check
+
+```bash
+npm run build -w @soddong/agentic-application-methodology-workbench
+npm run smoke -w @soddong/agentic-application-methodology-workbench -- --project <seed-project-root>
+```
+
+성공 시 `counts.stages`, `counts.activities`, `counts.tasks`, `counts.steps`가 0보다 큰 JSON 결과를 출력한다.

package/docs/publishing.md

@@ -0,0 +1,19 @@
+# Publishing
+
+초기에는 Platform workspace package로 검증한다.
+
+publish 후보가 되기 전 다음을 확인한다.
+
+```text
+- build/typecheck
+- CLI server boot
+- seed project smoke test
+- config schema 정합성
+- Authoring/Tutorial mode contract 정합성
+- Landing page와 Phase tab navigation 정합성
+- AI-Agent SDLC seed project config 로딩
+- 브라우저 시각 검수
+- npm pack dry-run 포함 파일
+```
+
+공식 registry publish 전에는 smoke test의 `--project`가 Platform root가 아니라 실제 Bundle/Seed project root를 가리키는지 확인한다.

package/docs/usage.md

@@ -0,0 +1,113 @@
+# Usage
+
+## Start Workbench For A Seed Project
+
+```bash
+npx --no-install agentic-methodology-workbench \
+  --project /Users/a07468/Downloads/IMPORTANT/agentic-methodology-ai-agent-sdlc
+```
+
+Workbench package는 Platform repository가 제공하지만, 실제 화면 데이터는 Bundle/Seed project의 `ui/workbench.config.json`과 `seedRoot` 아래 seed JSON을 기준으로 로딩한다. Platform root에서 실행하면 package fallback config만 사용되므로 실제 AI-Agent SDLC tree와 산출물 표준이 표시되지 않는다.
+
+## Mode Policy
+
+Authoring과 Tutorial은 별도 UI 기반이 아니라 하나의 Workbench shell에서 전환되는 모드다.
+
+| Mode | 목적 | Step 선택 시 동작 |
+| --- | --- | --- |
+| `Authoring` | Bundle/Seed 작성자가 Task/Step 정의와 실행 지시문을 보완한다. | 선택된 Step row 아래에 editor detail을 접고 펼칠 수 있게 표시한다. |
+| `Tutorial` | Execution 또는 조회 사용자가 방법론 구조와 산출물 표준을 read-only로 확인한다. | 동일한 tree row를 read-only로 표시하고 editor detail은 표시하지 않는다. |
+
+## Landing And Phase Navigation
+
+초기 화면은 Bundle/Seed project의 lifecycle seed를 읽어 방법론 라이프사이클 모델 개요를 표시한다. lifecycle model을 선택하면 현재 Workbench shell로 진입한다.
+
+Workbench shell의 좌측 tree 패널은 Phase tab을 상단에 표시한다. tab을 선택하면 해당 Phase의 Stage, Activity, Task, Step tree와 산출물 표준 패널을 갱신한다.
+
+## Endpoints
+
+| Endpoint | 목적 |
+| --- | --- |
+| `/api/health` | Workbench server 상태 확인 |
+| `/api/workbench/config` | 대상 project config 확인 |
+| `/api/workbench/overview` | UI shell overview ViewModel 확인 |
+| `/api/workbench/lifecycle` | Lifecycle, Phase, Process, seed count 조회 |
+| `/api/workbench/phases` | 기본 Phase의 Process, Stage, Activity 구조 조회 |
+| `/api/workbench/phases/:phaseCode` | 지정 Phase의 Process, Stage, Activity 구조 조회 |
+| `/api/workbench/activities` | 대표 Activity의 Task/Step/Artifact 구조 조회 |
+| `/api/workbench/activities/:activityCode/authoring` | Activity별 Task/Step 구조와 authoring draft 조회 |
+| `/api/workbench/artifacts` | 대표 Artifact Standard 구조 조회 |
+| `/api/workbench/governance` | Criteria, Handoff, generated output link 조회 |
+
+Workbench의 표준 계층과 한글 표기는 다음을 따른다.
+
+```text
+Lifecycle 생애주기
+  -> Phase 페이즈
+    -> Process 프로세스
+      -> Stage 단계
+        -> Activity 활동
+          -> Task 작업
+            -> Step 절차
+```
+
+## Authoring Draft
+
+Workbench는 원본 seed JSON을 직접 수정하지 않는다. UI에서 Step을 선택하고 title, execution mode, instruction, script path를 수정하면 다음 API로 draft를 저장한다.
+
+| Endpoint | Method | 목적 |
+| --- | --- | --- |
+| `/api/workbench/authoring/steps/:stepCode/draft` | `PUT` | Step authoring 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 authoring draft 저장 및 검증 |
+
+기본 저장 위치는 다음과 같다.
+
+```text
+methodology-authoring/drafts
+```
+
+Step draft apply는 다음 seed 필드만 변경한다.
+
+| Draft field | Seed field |
+| --- | --- |
+| `title` | `stepTitle` |
+| `executionModeCode` | `executionModeCode` |
+| `instruction` | `stepInstruction` |
+
+## Task Step Authoring Source
+
+Task의 Step을 정의할 때는 seed `steps.json`을 직접 편집하지 않고 Task별 authoring source를 먼저 생성한다.
+
+```bash
+npx --no-install agentic-methodology-workbench scaffold-task-source \
+  --project /Users/a07468/Downloads/IMPORTANT/agentic-methodology-ai-agent-sdlc \
+  --task define_component_function_function_candidate_identification
+```
+
+생성 구조는 다음과 같다.
+
+```text
+methodology-authoring/tasks/{taskCode}/
+  task.md
+  steps/{stepCode}/
+    step.md
+    instruction.md
+    script.md
+    validation.md
+    samples/.gitkeep
+```
+
+`task.md`와 `step.md`는 authoring 정의 원천이고, `instruction.md`, `script.md`, `validation.md`는 실행 모드와 검증 기준을 구체화한다. 검증된 내용만 Workbench draft/apply workflow를 통해 seed JSON으로 반영한다.
+
+## Smoke Test
+
+개발 중에는 실제 Bundle/Seed project를 대상으로 최소 smoke test를 수행한다.
+
+```bash
+npm run build -w @soddong/agentic-application-methodology-workbench
+npm run smoke -w @soddong/agentic-application-methodology-workbench -- --project /Users/a07468/Downloads/IMPORTANT/agentic-methodology-ai-agent-sdlc
+```
+
+이 smoke test는 브라우저 screenshot 검증이 아니라 API/ViewModel, HTML shell, CSS/JS 계약을 확인한다. 실제 시각 품질은 별도 화면 검수로 확인한다.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@soddong/agentic-application-methodology-workbench",
+  "version": "0.1.0",
+  "description": "Reusable methodology authoring workbench for Agentic Platform seed bundle projects",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "agentic-methodology-workbench": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "docs",
+    "schemas"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "dev": "npm run build && node dist/cli.js",
+    "smoke": "node scripts/smoke-workbench.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/schemas/workbench-config.schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://soddong.github.io/agentic-platform/schemas/workbench-config.schema.json",
+  "title": "Methodology Workbench Config",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "workbenchId",
+    "title",
+    "methodologyPackageName",
+    "bundleCode",
+    "seedRoot"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "0.1"
+    },
+    "workbenchId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "experienceMode": {
+      "type": "string",
+      "enum": [
+        "authoring",
+        "execution"
+      ],
+      "default": "authoring"
+    },
+    "methodologyPackageName": {
+      "type": "string",
+      "minLength": 1
+    },
+    "bundleCode": {
+      "type": "string",
+      "minLength": 1
+    },
+    "seedRoot": {
+      "type": "string",
+      "minLength": 1
+    },
+    "uiPlanningRoot": {
+      "type": "string"
+    },
+    "defaultRoute": {
+      "type": "string"
+    },
+    "routes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "routeId",
+          "label",
+          "path",
+          "viewModel"
+        ],
+        "properties": {
+          "routeId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "label": {
+            "type": "string",
+            "minLength": 1
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "viewModel": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "authoringSources": {
+      "type": "object",
+      "properties": {
+        "scenariosRoot": {
+          "type": "string"
+        },
+        "tasksRoot": {
+          "type": "string"
+        },
+        "stepAssetsRoot": {
+          "type": "string"
+        },
+        "artifactSamplesRoot": {
+          "type": "string"
+        },
+        "draftsRoot": {
+          "type": "string"
+        },
+        "generatedDocsRoot": {
+          "type": "string"
+        },
+        "generatedOutputsRoot": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}