From cb8a4336f0a348a51d852e0f833d102882162060 Mon Sep 17 00:00:00 2001
From: Samgu Lee <cable8mm@gmail.com>
Date: Fri, 12 Jun 2026 23:10:42 +0900
Subject: [PATCH] docs: review `/tools` content

---
 src/content/tools/ai-issue.mdx | 181 +++++++++++++++++++++++++++++++--
 src/content/tools/index.mdx    | 159 +++++++++++++++++++++++++++--
 2 files changed, 323 insertions(+), 17 deletions(-)

diff --git a/src/content/tools/ai-issue.mdx b/src/content/tools/ai-issue.mdx
index c6aabc5..3ad4f85 100644
--- a/src/content/tools/ai-issue.mdx
+++ b/src/content/tools/ai-issue.mdx
@@ -1,22 +1,187 @@
 ---
-title: 'ai-issue'
+title: 'AI Issue Publisher'
 version: 'v1'
-description: 'Issue-shaped workflow asset for AI-native product development.'
+description: 'AI Issue Publisher는 REPL Works용 Issue 생성 도구다.'
 publishedAt: '2026-06-12T00:00:00Z'
 ---
 
+아이디어, 대화, 작업 요청을 실행 가능한 GitHub Issue로 변환한다.
+
+[Github 바로가기](https://github.com/replworks/ai-issue)
+
+---
+
 ## Purpose
 
-Convert product work into issue-ready structure that an execution AI can implement.
+다음 문제를 해결한다.
+
+```text
+생각은 있다.
+
+하지만 실행 가능한 작업은 없다.
+```
+
+---
+
+ai-issue는 이를 다음 형태로 변환한다.
+
+```text
+Idea
+↓
+Issue
+↓
+Execution AI
+```
+
+---
+
+## Why It Exists
+
+대부분의 AI 프로젝트는 다음 문제를 겪는다.
+
+```text
+작업 지시가 모호하다.
+
+범위가 불명확하다.
+
+완료 기준이 없다.
+```
 
-## Installation
+---
+
+이 경우 Execution AI는
+
+- 범위를 추측한다.
+- 기능을 추가한다.
+- 의도를 오해한다.
+
+---
 
-Use the framework assets directly in a Git-backed REPL Works project.
+ai-issue는 이러한 문제를 줄인다.
+
+---
+
+## Workflow
+
+일반적인 흐름
+
+```text
+Discussion
+↓
+Issue
+↓
+Branch
+↓
+PR
+↓
+Review
+↓
+Merge
+```
+
+---
+
+ai-issue는 Discussion과 Issue 사이를 담당한다.
+
+---
+
+## Output
+
+생성되는 Issue는 일반적으로 다음을 포함한다.
+
+- Problem
+- Goal
+- Scope
+- Constraints
+- Acceptance Criteria
+- Expected Outcome
+
+---
+
+Execution AI는 Issue만 읽고 작업을 시작할 수 있어야 한다.
+
+---
 
 ## Usage
 
-Apply `ai-issue` when a task needs a clean issue description, clear acceptance criteria, and execution boundaries.
+다음 상황에서 사용한다.
+
+```text
+새로운 기능
+
+버그 수정
+
+문서 작업
+
+리팩토링
+
+운영 작업
+```
+
+---
+
+작업을 명확하게 정의해야 할 때 사용한다.
+
+---
+
+## Relationship
+
+```text
+Workflow
+↓
+Issue
+↓
+Execution
+```
+
+---
+
+ai-issue는 REPL Works Workflow를 지원하는 도구다.
+
+---
+
+프레임워크를 대체하지 않는다.
+
+---
+
+## Repository
+
+ai-issue는 REPL Works Compatible 프로젝트에 적용할 수 있다.
+
+---
+
+프로젝트별로 독립적으로 사용할 수 있다.
+
+---
+
+GitHub 기반 워크플로와 함께 사용하는 것을 권장한다.
+
+---
+
+## Key Principle
+
+좋은 Issue는 작업을 설명하지 않는다.
+
+좋은 Issue는 작업을 실행 가능하게 만든다.
+
+---
+
+## Future Direction
+
+ai-issue는 REPL Works 생태계의 첫 번째 도구다.
+
+---
+
+향후 Prompt, Document, Workflow 자동화를 위한 추가 도구가 만들어질 수 있다.
+
+---
+
+ai-issue의 목표는 더 많은 이슈를 만드는 것이 아니다.
+
+---
+
+더 적은 설명으로,
 
-## Repository Link
+더 정확하게,
 
-This tool is a framework asset and can be mirrored into compatible project repositories.
+AI가 작업할 수 있게 만드는 것이다.
diff --git a/src/content/tools/index.mdx b/src/content/tools/index.mdx
index 1fb0077..a3c0e79 100644
--- a/src/content/tools/index.mdx
+++ b/src/content/tools/index.mdx
@@ -1,22 +1,163 @@
 ---
-title: 'Tools'
+title: '도구(Tools)'
 version: 'v1'
-description: 'REPL Works ecosystem tools and framework assets.'
+description: '도구(Tools)는 ReplWorks framework 를 확장하고 자동화 합니다.'
 publishedAt: '2026-06-12T00:00:00Z'
 ---
 
-## Purpose
+REPL Works는 도구를 제품으로 보지 않는다.
 
-Provide REPL Works ecosystem tools as framework assets.
+도구는 프레임워크를 실행하기 위한 자산(Framework Assets)이다.
 
-## Initial Tool
+---
+
+Workflow가 반복되면,
+
+반복되는 작업은 도구가 될 수 있다.
+
+---
+
+## Why Tools Exist
+
+REPL Works는 다음을 표준화한다.
+
+```text
+Workflow
+
+Prompts
+
+Documents
+```
+
+---
+
+도구는 이러한 표준을 자동화한다.
+
+---
+
+## Evolution
+
+일반적으로 다음 순서로 발전한다.
+
+```text
+Manual Process
+↓
+Prompt
+↓
+Document
+↓
+Tool
+```
+
+---
 
-- [ai-issue](/tools/ai-issue)
+충분히 반복되고 검증된 작업만 도구가 된다.
+
+---
+
+## Current Tools
+
+### AI Issue Publisher
+
+GitHub Issue를 REPL Works 방식으로 생성하기 위한 도구.
+
+---
+
+목적
+
+```text
+Idea
+↓
+Issue
+```
+
+전환을 단순화한다.
+
+---
+
+주요 기능
+
+- Issue 생성
+- 템플릿 적용
+- 표준 구조 유지
+- AI 친화적 작업 정의
+
+---
+
+[View Tool](/tools/ai-issue)
+
+---
 
 ## Future Tools
 
-- ai-prompt
+REPL Works는 실제 사용 경험을 통해 새로운 도구를 추가할 수 있다.
 
-## Structure
+---
+
+예시
+
+```text
+ai-prompt
+
+ai-sync
+
+ai-review
+
+ai-memory
+```
+
+---
+
+도구 이름보다 중요한 것은 문제 정의다.
+
+---
+
+반복되는 작업이 충분히 검증되면 도구가 된다.
+
+---
+
+## Relationship
+
+```text
+Workflow
+↓
+Prompts
+↓
+Documents
+↓
+Tools
+```
+
+---
+
+도구는 프레임워크를 대체하지 않는다.
+
+---
+
+도구는 프레임워크를 더 쉽게 실행하게 만든다.
+
+---
+
+## Key Principle
+
+좋은 도구는 새로운 프로세스를 만들지 않는다.
+
+좋은 도구는 이미 검증된 프로세스를 자동화한다.
+
+---
+
+## Why It Matters
+
+REPL Works의 목표는 더 많은 AI 도구를 만드는 것이 아니다.
+
+---
+
+더 적은 비용으로,
+
+더 일관되게,
+
+더 오래 유지되는 프로젝트를 만드는 것이다.
+
+---
 
-Tools are organized as reusable assets, not standalone products.
+도구는 그 목표를 지원하기 위해 존재한다.