docs: update README files to clarify the roles of the SSOT components enhance descriptions of Agent Skills, and introduce the Drawkit for architecture visualization. Improve consistency in terminology and structure across both English and Korean versions.

README.md

@@ -59,10 +59,10 @@ Act Operator implements this with three layers:
 | Layer | Role | How Act implements it |
 |-------|------|----------------------|
 | **Scaffolding** | Structure assembled before the first agent prompt | `act new` — generates the full project skeleton with module conventions and base classes baked in |
-| **Executable SSOT** | Knowledge encoded as living files agents read at runtime | Agent Skills — 50+ reference patterns, decision trees, and architecture templates in `.claude/skills/` |
+| **Executable SSOT** | Knowledge encoded as living files that agents and humans read at runtime | Act Template (project structure, CI, base classes, configs), Agent Skills (50+ patterns for agents), Drawkit (visual architecture for teams) |
 | **Feedback Loop** | Specs that survive across sessions and keep agents aligned | `CLAUDE.md` — architecture diagrams, node specifications, and development commands generated by skills and maintained across sessions |
 
-These three layers work together. Scaffolding gives agents a consistent starting point. Skills give them the knowledge to reason correctly within that structure. CLAUDE.md gives them persistent memory of what was designed — so the agent in your next session picks up exactly where the last one left off.
+These three layers work together. Scaffolding gives agents a consistent starting point. The SSOT layer provides three forms of executable knowledge: the **Act Template** establishes project conventions (CI workflows, base classes, test structure, configs), **Skills** give agents the patterns to reason correctly within that structure, and the **Drawkit** gives teams a shared visual vocabulary for architecture diagrams. CLAUDE.md gives them persistent memory of what was designed — so the agent in your next session picks up exactly where the last one left off.
 
 > **Terminology**: An **Act** is a harness instance — your LangGraph project. A **Cast** is a graph unit within it (one StateGraph = one Cast). A single Act can contain multiple Casts as independent packages in a monorepo.
 
@@ -114,11 +114,23 @@ opencode run "Design a customer support chatbot"
 
 OpenCode reads environment variables from `.env` at the project root (configured in `langgraph.json` as `env: ".env"`).
 
-## Skills: The Executable SSOT
+## The Executable SSOT
 
 Traditional teams share LangGraph knowledge through wikis, architecture docs, and tribal memory. The problem: documentation decays, wikis go stale, and tribal memory doesn't survive team changes.
 
-Skills encode that knowledge as **living files that agents read directly**. Instead of you telling the agent what patterns exist, the skill shows the agent the exact patterns, decision trees, and reference implementations it needs — at the moment it needs them. All patterns reference official LangChain 1.0+/LangGraph 1.0+ documentation, not guesswork. The skills are lean by design: context-aware guidance without unnecessary code generation, keeping token usage low across long sessions.
+The harness encodes that knowledge as **living files** — not static documentation, but executable references that agents and humans read directly. Act Operator scaffolds three complementary SSOT components:
+
+| Component | Audience | What it provides |
+|-----------|----------|------------------|
+| **Act Template** (scaffold) | Developers | The project skeleton itself — CI workflows, base classes, test structure, pre-commit hooks, monorepo config, `.env.example`, `TEMPLATE_README.md` usage guide |
+| **Agent Skills** (`.claude/skills/`) | AI agents | 50+ reference patterns, decision trees, architecture templates — agents read these at runtime |
+| **Drawkit** (`drawkit.xml`) | Teams | Pre-defined draw.io shapes for Act architecture — a shared visual vocabulary for human-to-human communication |
+
+Each component targets a different audience while referencing the same underlying conventions. The Act Template establishes the structural foundation that agents and developers both work within; Skills tell agents how to build correctly inside that structure; the Drawkit tells teams how to communicate architecture visually.
+
+### Agent Skills
+
+Skills encode LangGraph knowledge as files that agents read directly. Instead of you telling the agent what patterns exist, the skill shows the agent the exact patterns, decision trees, and reference implementations it needs — at the moment it needs them. All patterns reference official LangChain 1.0+/LangGraph 1.0+ documentation, not guesswork. The skills are lean by design: context-aware guidance without unnecessary code generation, keeping token usage low across long sessions.
 
 ```
 .claude/skills/
@@ -181,6 +193,16 @@ The CLAUDE.md is not static documentation — it is a **living specification** t
 
 This loop is the harness feedback mechanism: every agent session anchors to the same spec, producing consistent output regardless of who prompts it.
 
+## Architecture Diagram Kit (Drawkit)
+
+The `drawkit.xml` file scaffolded in every Act project provides pre-defined [draw.io](https://app.diagrams.net/) shapes for designing Act architecture visually.
+
+> **Note**: Drawkit is for **human-to-human communication** — sharing architecture with teammates, stakeholders, or documentation.
+> For **agent-to-agent communication**, use the Mermaid charts in `CLAUDE.md` generated by `@architecting-act`.
+> For **runtime inspection**, use the LangGraph Development Server (LangSmith).
+
+Import `drawkit.xml` into draw.io's Scratchpad to get drag-and-drop Act components. See `TEMPLATE_README.md` in your generated project for detailed import instructions and examples.
+
 ## Skill-Driven Development Flow
 
 ```mermaid
@@ -317,6 +339,7 @@ my_workflow/
 │   ├── cast_tests/               # Graph integration tests
 │   └── node_tests/               # Node unit tests
 ├── CLAUDE.md                     # Root spec: Act overview + Cast index
+├── drawkit.xml                   # draw.io shapes for architecture diagrams
 ├── langgraph.json                # LangGraph entry points
 ├── pyproject.toml                # Monorepo workspace (uv workspace, shared deps)
 └── TEMPLATE_README.md            # Template usage guide

README_KR.md

@@ -59,10 +59,10 @@ Act Operator는 이를 세 가지 레이어로 구현합니다:
 | 레이어 | 역할 | Act에서의 구현 |
 |--------|------|---------------|
 | **스캐폴딩** | 첫 번째 에이전트 프롬프트 이전에 조립되는 구조 | `act new` — 모듈 컨벤션과 베이스 클래스가 내장된 완전한 프로젝트 스켈레톤 생성 |
-| **실행 가능한 SSOT** | 에이전트가 런타임에 읽는 살아있는 파일로 인코딩된 지식 | Agent Skills — `.claude/skills/`의 50개 이상 참조 패턴, 결정 트리, 아키텍처 템플릿 |
+| **실행 가능한 SSOT** | 에이전트와 사람이 런타임에 읽는 살아있는 파일로 인코딩된 지식 | Act Template (프로젝트 구조, CI, 베이스 클래스, 설정), Agent Skills (에이전트용 50개 이상 패턴), Drawkit (팀용 시각적 아키텍처) |
 | **피드백 루프** | 세션을 넘어 에이전트를 정렬 상태로 유지하는 명세 | `CLAUDE.md` — 스킬이 생성하고 세션 간 유지되는 아키텍처 다이어그램, 노드 명세, 개발 명령어 |
 
-이 세 레이어는 함께 작동합니다. 스캐폴딩은 에이전트에게 일관된 시작점을 제공합니다. 스킬은 그 구조 내에서 올바르게 추론할 수 있는 지식을 제공합니다. CLAUDE.md는 설계된 내용에 대한 지속적인 메모리를 제공합니다 — 다음 세션의 에이전트가 이전 세션이 중단된 지점에서 정확히 이어받을 수 있습니다.
+이 세 레이어는 함께 작동합니다. 스캐폴딩은 에이전트에게 일관된 시작점을 제공합니다. SSOT 레이어는 세 가지 형태의 실행 가능한 지식을 제공합니다: **Act Template**은 프로젝트 컨벤션(CI 워크플로우, 베이스 클래스, 테스트 구조, 설정)을 확립하고, **스킬**은 그 구조 안에서 에이전트가 올바르게 추론할 수 있는 패턴을, **Drawkit**은 팀에게 아키텍처 다이어그램을 위한 공유 시각 어휘를 제공합니다. CLAUDE.md는 설계된 내용에 대한 지속적인 메모리를 제공합니다 — 다음 세션의 에이전트가 이전 세션이 중단된 지점에서 정확히 이어받을 수 있습니다.
 
 > **용어 정리**: **Act**는 하네스 인스턴스 — LangGraph 프로젝트입니다. **Cast**는 그 안의 그래프 단위입니다 (하나의 StateGraph = 하나의 Cast). 하나의 Act는 모노레포 안에 독립적인 패키지로 여러 Cast를 포함할 수 있습니다.
 
@@ -114,11 +114,23 @@ opencode run "고객 지원 챗봇을 설계해줘"
 
 OpenCode는 프로젝트 루트의 `.env`를 사용합니다(`langgraph.json`의 `env: ".env"` 설정).
 
-## 스킬: 실행 가능한 SSOT
+## 실행 가능한 SSOT
 
 전통적인 팀은 LangGraph 지식을 위키, 아키텍처 문서, 구전 지식으로 공유합니다. 문제는 문서가 낡아가고, 위키가 오래되고, 구전 지식이 팀원 변화에서 살아남지 못한다는 점입니다.
 
-스킬은 그 지식을 **에이전트가 직접 읽는 살아있는 파일**로 인코딩합니다. 에이전트에게 어떤 패턴이 존재하는지 당신이 설명할 필요 없이, 스킬이 에이전트에게 필요한 정확한 패턴, 결정 트리, 참조 구현을 직접 보여줍니다. 모든 패턴은 추측이 아닌 공식 LangChain 1.0+/LangGraph 1.0+ 문서를 참조합니다. 스킬은 설계상 간결합니다: 불필요한 코드 생성 없이 컨텍스트 인식 가이드를 제공하여 긴 세션에서도 토큰 사용을 최소화합니다.
+하네스는 이 지식을 **살아있는 파일**로 인코딩합니다 — 정적 문서가 아닌, 에이전트와 사람이 직접 읽는 실행 가능한 참조입니다. Act Operator는 세 가지 상호보완적 SSOT 구성요소를 스캐폴딩합니다:
+
+| 구성요소 | 대상 | 제공하는 것 |
+|----------|------|------------|
+| **Act Template** (scaffold) | 개발자 | 프로젝트 스켈레톤 자체 — CI 워크플로우, 베이스 클래스, 테스트 구조, pre-commit 훅, 모노레포 설정, `.env.example`, `TEMPLATE_README.md` 사용 가이드 |
+| **Agent Skills** (`.claude/skills/`) | AI 에이전트 | 50개 이상 참조 패턴, 결정 트리, 아키텍처 템플릿 — 에이전트가 런타임에 읽음 |
+| **Drawkit** (`drawkit.xml`) | 팀 | draw.io용 Act 아키텍처 사전 정의 쉐이프 — 사람 간 커뮤니케이션을 위한 공유 시각 어휘 |
+
+각 구성요소는 서로 다른 대상을 겨냥하면서 동일한 기저 컨벤션을 참조합니다. Act Template은 에이전트와 개발자 모두가 작업하는 구조적 기반을 확립합니다. 스킬은 그 구조 안에서 에이전트가 올바르게 구축하는 방법을, Drawkit은 팀에게 아키텍처 시각화 방법을 알려줍니다.
+
+### Agent Skills
+
+스킬은 LangGraph 지식을 에이전트가 직접 읽는 파일로 인코딩합니다. 에이전트에게 어떤 패턴이 존재하는지 당신이 설명할 필요 없이, 스킬이 에이전트에게 필요한 정확한 패턴, 결정 트리, 참조 구현을 직접 보여줍니다. 모든 패턴은 추측이 아닌 공식 LangChain 1.0+/LangGraph 1.0+ 문서를 참조합니다. 스킬은 설계상 간결합니다: 불필요한 코드 생성 없이 컨텍스트 인식 가이드를 제공하여 긴 세션에서도 토큰 사용을 최소화합니다.
 
 ```
 .claude/skills/
@@ -181,6 +193,16 @@ CLAUDE.md는 정적 문서가 아닌 **살아있는 명세**입니다:
 
 이 루프가 하네스의 피드백 메커니즘입니다: 모든 에이전트 세션이 동일한 명세를 기준으로 하여, 누가 프롬프트를 입력하든 일관된 출력을 생성합니다.
 
+## 아키텍처 다이어그램 키트 (Drawkit)
+
+모든 Act 프로젝트에 스캐폴딩되는 `drawkit.xml` 파일은 [draw.io](https://app.diagrams.net/)에서 Act 아키텍처를 시각적으로 설계할 수 있는 사전 정의된 쉐이프를 제공합니다.
+
+> **참고**: Drawkit은 **사람 간 커뮤니케이션** — 팀원, 이해관계자, 문서와 아키텍처를 공유하기 위한 것입니다.
+> **에이전트 간 커뮤니케이션**에는 `@architecting-act`이 생성하는 `CLAUDE.md`의 Mermaid 차트를 사용하세요.
+> **런타임 검사**에는 LangGraph Development Server (LangSmith)를 사용하세요.
+
+draw.io의 Scratchpad에 `drawkit.xml`을 import하면 드래그 앤 드롭으로 Act 컴포넌트를 사용할 수 있습니다. 상세한 import 방법과 예시는 생성된 프로젝트의 `TEMPLATE_README.md`를 참조하세요.
+
 ## 스킬 기반 개발 흐름
 
 ```mermaid
@@ -317,6 +339,7 @@ my_workflow/
 │   ├── cast_tests/               # 그래프 통합 테스트
 │   └── node_tests/               # 노드 단위 테스트
 ├── CLAUDE.md                     # 루트 명세: Act 개요 + Cast 인덱스
+├── drawkit.xml                   # draw.io용 아키텍처 다이어그램 쉐이프
 ├── langgraph.json                # LangGraph 진입점
 ├── pyproject.toml                # 모노레포 워크스페이스 (uv workspace, 공유 의존성)
 └── TEMPLATE_README.md            # 템플릿 사용 가이드