aiwf 0.3.0 → 0.3.2

package/docs/CONTRIBUTING.md

@@ -1,406 +1,408 @@
-# aiwf 프로젝트 기여 가이드
+# Contributing to AIWF
 
-aiwf (AI Workflow Framework) 프로젝트에 기여해 주셔서 감사합니다! 이 문서는 프로젝트에 효과적으로 기여하는 방법을 안내합니다.
+Thank you for your interest in contributing to AIWF (AI Workflow Framework)! This guide will help you contribute effectively to the project.
 
-## 목차
+[한국어로 보기](CONTRIBUTING.ko.md)
 
-1. [기여하기 전에](#기여하기-전에)
-2. [개발 환경 설정](#개발-환경-설정)
-3. [기여 방법](#기여-방법)
-4. [코드 스타일 가이드](#코드-스타일-가이드)
-5. [테스트 작성](#테스트-작성)
-6. [Pull Request 가이드](#pull-request-가이드)
-7. [이슈 리포팅](#이슈-리포팅)
-8. [커뮤니티 가이드라인](#커뮤니티-가이드라인)
+## Table of Contents
 
-## 기여하기 전에
+1. [Before Contributing](#before-contributing)
+2. [Development Environment Setup](#development-environment-setup)
+3. [How to Contribute](#how-to-contribute)
+4. [Code Style Guide](#code-style-guide)
+5. [Writing Tests](#writing-tests)
+6. [Pull Request Guidelines](#pull-request-guidelines)
+7. [Issue Reporting](#issue-reporting)
+8. [Community Guidelines](#community-guidelines)
 
-### 프로젝트 이해
+## Before Contributing
 
-aiwf는 Claude Code와 통합된 AIWF 프로젝트 관리 프레임워크를 설치하는 NPM CLI 패키지입니다. 기여하기 전에 다음을 이해해 주세요:
+### Understanding the Project
 
-- **목적**: AI 기반 개발 워크플로우 프레임워크 배포
-- **대상 사용자**: Claude Code, Cursor, Windsurf 사용자
-- **핵심 기능**: GitHub에서 프레임워크 다운로드 및 설치
+AIWF is an NPM CLI package that installs the AI Workflow Framework integrated with Claude Code. Before contributing, please understand:
 
-### 행동강령
+- **Purpose**: Deploy AI-driven development workflow framework
+- **Target Users**: Claude Code, Cursor, and Windsurf users
+- **Core Function**: Download and install framework from GitHub
 
-우리는 모든 기여자가 존중받고 포용적인 환경을 만들기 위해 다음 원칙을 따릅니다:
+### Code of Conduct
 
-- **존중**: 모든 의견과 기여를 존중합니다
-- **포용성**: 다양한 배경과 경험을 가진 기여자를 환영합니다
-- **건설적 피드백**: 비판적 피드백도 건설적이고 도움이 되는 방향으로 제공합니다
-- **협력**: 문제 해결을 위해 함께 협력합니다
+We follow these principles to create a respectful and inclusive environment:
 
-## 개발 환경 설정
+- **Respect**: We respect all opinions and contributions
+- **Inclusivity**: We welcome contributors from diverse backgrounds
+- **Constructive Feedback**: We provide helpful and constructive criticism
+- **Collaboration**: We work together to solve problems
 
-### 필수 요구사항
+## Development Environment Setup
 
-- **Node.js**: 14.0.0 이상
-- **npm**: Node.js와 함께 설치됨
-- **Git**: 최신 버전
+### Prerequisites
 
-### 초기 설정
+- **Node.js**: 14.0.0 or higher
+- **npm**: Installed with Node.js
+- **Git**: Latest version
+
+### Initial Setup
 
 ```bash
-# 1. 리포지토리 포크
-# GitHub에서 https://github.com/aiwf/aiwf를 개인 계정으로 포크
+# 1. Fork the repository
+# Fork https://github.com/aiwf/aiwf on GitHub
 
-# 2. 로컬에 클론
+# 2. Clone locally
 git clone https://github.com/YOUR_USERNAME/aiwf.git
 cd aiwf
 
-# 3. 원본 리포지토리를 upstream으로 추가
+# 3. Add upstream remote
 git remote add upstream https://github.com/aiwf/aiwf.git
 
-# 4. 의존성 설치
+# 4. Install dependencies
 npm install
 
-# 5. 개발 환경 검증
-node index.js --force  # 로컬 테스트 실행
-npm test               # 테스트 실행 (설정 후)
-npm run lint           # 코드 스타일 검사 (설정 후)
+# 5. Verify development environment
+node index.js --force  # Run local test
+npm test               # Run tests
+npm run lint          # Check code style
 ```
 
-## 기여 방법
+## How to Contribute
 
-### 1. 이슈 기반 기여
+### 1. Issue-Based Contributions
 
-가장 권장하는 기여 방법입니다:
+The recommended way to contribute:
 
-1. **이슈 찾기**: [GitHub Issues](https://github.com/aiwf/aiwf/issues)에서 작업할 이슈 선택
-2. **이슈 할당**: 댓글로 작업 의사 표현
-3. **브랜치 생성**: `feature/issue-번호-간단한-설명` 형식
+1. **Find an Issue**: Select from [GitHub Issues](https://github.com/aiwf/aiwf/issues)
+2. **Assign Yourself**: Comment to express interest
+3. **Create Branch**: Use format `feature/issue-number-brief-description`
 
-### 2. 새로운 기능 제안
+### 2. Proposing New Features
 
-새로운 기능을 제안하고 싶다면:
+To propose new features:
 
-1. **이슈 생성**: Feature Request 템플릿 사용
-2. **토론 참여**: 커뮤니티와 기능에 대해 논의
-3. **승인 후 개발**: 승인된 후 개발 시작
+1. **Create Issue**: Use Feature Request template
+2. **Join Discussion**: Discuss with community
+3. **Start Development**: Begin after approval
 
-### 3. 버그 수정
+### 3. Bug Fixes
 
-버그를 발견했다면:
+If you found a bug:
 
-1. **이슈 확인**: 이미 리포트된 버그인지 확인
-2. **새 이슈 생성**: Bug Report 템플릿 사용
-3. **재현 가능한 예제**: 최소한의 재현 가능한 예제 포함
+1. **Check Issues**: Verify if already reported
+2. **Create New Issue**: Use Bug Report template
+3. **Provide Example**: Include minimal reproducible example
 
-## 코드 스타일 가이드
+## Code Style Guide
 
-### JavaScript 스타일
+### JavaScript Style
 
 ```javascript
-// 좋음: ES6+ 문법 사용
+// Good: Use ES6+ syntax
 const apiUrl = "https://api.github.com";
 const fetchData = async (url) => {
   try {
     const response = await fetch(url);
     return await response.json();
   } catch (error) {
-    console.error("API 호출 실패:", error);
+    console.error("API call failed:", error);
     throw error;
   }
 };
 
-// 피하기: var 사용, 콜백 헬
+// Avoid: var usage, callback hell
 var oldUrl = "https://api.github.com";
 function fetchDataOld(url, callback) {
-  // 구식 패턴
+  // Old pattern
 }
 ```
 
-### 명명 규칙
+### Naming Conventions
 
-- **변수/함수**: camelCase (`fetchGitHubContent`)
-- **상수**: UPPER_SNAKE_CASE (`API_BASE_URL`)
-- **파일명**: kebab-case (`github-api.js`)
-- **클래스**: PascalCase (`GitHubClient`)
+- **Variables/Functions**: camelCase (`fetchGitHubContent`)
+- **Constants**: UPPER_SNAKE_CASE (`API_BASE_URL`)
+- **File Names**: kebab-case (`github-api.js`)
+- **Classes**: PascalCase (`GitHubClient`)
 
-### 주석 가이드
+### Comment Guidelines
 
 ```javascript
 /**
- * GitHub API에서 리포지토리 내용을 가져옵니다.
- * @param {string} repoUrl - 리포지토리 URL
- * @param {string} path - 가져올 파일/디렉토리 경로
- * @returns {Promise<Object>} API 응답 데이터
- * @throws {Error} 네트워크 오류 또는 API 제한 시 발생
+ * Fetches repository content from GitHub API.
+ * @param {string} repoUrl - Repository URL
+ * @param {string} path - Path to file/directory
+ * @returns {Promise<Object>} API response data
+ * @throws {Error} On network error or API limits
  */
 async function fetchRepositoryContent(repoUrl, path) {
-  // 입력 검증
+  // Input validation
   if (!repoUrl || !path) {
-    throw new Error("리포지토리 URL과 경로는 필수입니다");
+    throw new Error("Repository URL and path are required");
   }
 
-  // API 호출 구현...
+  // API call implementation...
 }
 ```
 
-### ESLint 및 Prettier
+### ESLint and Prettier
 
-프로젝트는 ESLint와 Prettier를 사용합니다:
+The project uses ESLint and Prettier:
 
 ```bash
-# 코드 스타일 검사
+# Check code style
 npm run lint
 
-# 자동 수정
+# Auto-fix issues
 npm run lint:fix
 
-# 코드 포맷팅
+# Format code
 npm run format
 ```
 
-## 테스트 작성
+## Writing Tests
 
-### 테스트 철학
+### Testing Philosophy
 
-- **모든 새로운 기능**에는 테스트가 필요합니다
-- **버그 수정** 시 해당 버그를 확인하는 테스트를 추가합니다
-- **기존 테스트를 깨뜨리지** 않도록 합니다
+- **All new features** require tests
+- **Bug fixes** should include tests that verify the fix
+- **Don't break** existing tests
 
-### 테스트 구조
+### Test Structure
 
 ```javascript
 // tests/unit/github-api.test.js
 import { jest } from "@jest/globals";
 import { fetchGitHubContent } from "../../index.js";
 
-describe("GitHub API 함수들", () => {
+describe("GitHub API functions", () => {
   beforeEach(() => {
     jest.clearAllMocks();
   });
 
   describe("fetchGitHubContent", () => {
-    test("성공적으로 데이터를 가져와야 함", async () => {
-      // Given (준비)
+    test("should fetch data successfully", async () => {
+      // Given
       const mockUrl = "https://api.github.com/repos/test/repo";
       const expectedData = { name: "test-repo" };
 
-      // When (실행)
+      // When
       const result = await fetchGitHubContent(mockUrl);
 
-      // Then (검증)
+      // Then
       expect(result).toEqual(expectedData);
     });
 
-    test("잘못된 URL에 대해 에러를 발생시켜야 함", async () => {
+    test("should throw error for invalid URL", async () => {
       // Given & When & Then
       await expect(fetchGitHubContent("invalid-url")).rejects.toThrow(
-        "올바르지 않은 URL입니다"
+        "Invalid URL"
       );
     });
   });
 });
 ```
 
-### 테스트 실행
+### Running Tests
 
 ```bash
-# 모든 테스트 실행
+# Run all tests
 npm test
 
-# 감시 모드로 실행
+# Run in watch mode
 npm run test:watch
 
-# 커버리지 포함
+# Run with coverage
 npm run test:coverage
 ```
 
-## Pull Request 가이드
+## Pull Request Guidelines
 
-### PR 생성 전 체크리스트
+### Pre-PR Checklist
 
-- [ ] 최신 `develop` 브랜치로부터 생성된 브랜치
-- [ ] 모든 테스트 통과 (`npm test`)
-- [ ] 린팅 검사 통과 (`npm run lint`)
-- [ ] 관련된 기존 이슈가 있다면 링크 포함
-- [ ] 변경사항에 대한 테스트 추가
+- [ ] Branch created from latest `main`
+- [ ] All tests pass (`npm test`)
+- [ ] Linting passes (`npm run lint`)
+- [ ] Related issue linked if applicable
+- [ ] Tests added for changes
 
-### PR 제목 형식
+### PR Title Format
 
 ```
 <type>(<scope>): <description>
 
-예시:
-feat(cli): GitHub API 재시도 로직 추가
-fix(installer): 백업 파일 타임스탬프 오류 수정
-docs(readme): 설치 가이드 업데이트
+Examples:
+feat(cli): add GitHub API retry logic
+fix(installer): fix backup file timestamp error
+docs(readme): update installation guide
 ```
 
-### PR 설명 템플릿
+### PR Description Template
 
 ```markdown
-## 변경사항 요약
+## Summary of Changes
 
-<!-- 이 PR에서 무엇을 변경했는지 간단히 설명 -->
+<!-- Brief description of what this PR changes -->
 
-## 관련 이슈
+## Related Issues
 
-<!-- 관련된 이슈가 있다면 링크 -->
+<!-- Link related issues if any -->
 
 Closes #123
 
-## 변경 유형
+## Type of Change
 
-- [ ] 버그 수정 (기존 기능을 깨뜨리지 않는 변경사항)
-- [ ] 새로운 기능 (기존 기능을 깨뜨리지 않는 새로운 기능)
-- [ ] Breaking change (기존 기능에 영향을 주는 변경사항)
-- [ ] 문서 업데이트
+- [ ] Bug fix (non-breaking change fixing an issue)
+- [ ] New feature (non-breaking change adding functionality)
+- [ ] Breaking change (fix or feature causing existing functionality to change)
+- [ ] Documentation update
 
-## 테스트 방법
+## How to Test
 
-<!-- 이 변경사항을 어떻게 테스트했는지 설명 -->
+<!-- Describe how to test these changes -->
 
-1. 단계 1
-2. 단계 2
-3. 예상 결과
+1. Step 1
+2. Step 2
+3. Expected result
 
-## 스크린샷 (해당하는 경우)
+## Screenshots (if applicable)
 
-<!-- 시각적 변경사항이 있다면 스크린샷 포함 -->
+<!-- Include screenshots for visual changes -->
 
-## 추가 참고사항
+## Additional Notes
 
-<!-- 리뷰어가 알아야 할 추가 정보 -->
+<!-- Any additional information for reviewers -->
 ```
 
-### 코드 리뷰 과정
+### Code Review Process
 
-1. **자동 검사**: GitHub Actions가 자동으로 테스트 실행
-2. **코드 리뷰**: 프로젝트 유지보수자가 코드 검토
-3. **피드백 대응**: 리뷰 댓글에 적극적으로 응답
-4. **승인 및 머지**: 승인 후 squash merge로 병합
+1. **Automated Checks**: GitHub Actions run tests automatically
+2. **Code Review**: Project maintainers review code
+3. **Address Feedback**: Respond actively to review comments
+4. **Approval & Merge**: Squash merge after approval
 
-## 이슈 리포팅
+## Issue Reporting
 
-### 버그 리포트
+### Bug Reports
 
-다음 정보를 포함해 주세요:
+Please include:
 
 ```markdown
-## 버그 설명
+## Bug Description
 
-<!-- 버그에 대한 명확하고 간단한 설명 -->
+<!-- Clear and concise description of the bug -->
 
-## 재현 단계
+## Steps to Reproduce
 
-1. '...'로 이동
-2. '...'를 클릭
-3. 아래로 스크롤하여 '...'를 확인
-4. 오류 발생
+1. Go to '...'
+2. Click on '...'
+3. Scroll down to '...'
+4. See error
 
-## 예상 동작
+## Expected Behavior
 
-<!-- 예상했던 동작에 대한 설명 -->
+<!-- Description of expected behavior -->
 
-## 실제 동작
+## Actual Behavior
 
-<!-- 실제로 일어난 일에 대한 설명 -->
+<!-- Description of what actually happened -->
 
-## 환경
+## Environment
 
-- OS: [예: macOS 12.0]
-- Node.js 버전: [예: 18.0.0]
-- aiwf 버전: [예: 1.0.0]
+- OS: [e.g., macOS 12.0]
+- Node.js version: [e.g., 18.0.0]
+- aiwf version: [e.g., 1.0.0]
 
-## 추가 컨텍스트
+## Additional Context
 
-<!-- 문제에 대한 추가 정보나 스크린샷 -->
+<!-- Any additional information or screenshots -->
 ```
 
-### 기능 요청
+### Feature Requests
 
 ```markdown
-## 기능 설명
+## Feature Description
 
-<!-- 원하는 기능에 대한 설명 -->
+<!-- Description of the desired feature -->
 
-## 문제점
+## Problem Statement
 
-<!-- 이 기능이 해결할 문제에 대한 설명 -->
+<!-- Description of the problem this feature would solve -->
 
-## 제안하는 해결책
+## Proposed Solution
 
-<!-- 어떻게 구현되었으면 하는지에 대한 설명 -->
+<!-- Description of how you'd like it implemented -->
 
-## 대안
+## Alternatives
 
-<!-- 고려한 다른 해결책들 -->
+<!-- Other solutions you've considered -->
 
-## 추가 컨텍스트
+## Additional Context
 
-<!-- 기능 요청에 대한 추가 정보나 스크린샷 -->
+<!-- Any additional information or screenshots -->
 ```
 
-## 커뮤니티 가이드라인
+## Community Guidelines
 
-### 소통 채널
+### Communication Channels
 
-- **GitHub Issues**: 버그 리포트, 기능 요청
-- **GitHub Discussions**: 일반적인 질문, 아이디어 논의
-- **Pull Request**: 코드 리뷰, 기술적 논의
+- **GitHub Issues**: Bug reports, feature requests
+- **GitHub Discussions**: General questions, ideas
+- **Pull Requests**: Code review, technical discussions
 
-### 질문하기
+### Asking Questions
 
-좋은 질문을 위한 가이드:
+Guidelines for good questions:
 
-1. **검색 먼저**: 이미 답변된 질문인지 확인
-2. **구체적으로**: 애매한 질문보다는 구체적인 상황 설명
-3. **재현 가능한 예제**: 문제를 재현할 수 있는 최소한의 예제 제공
-4. **환경 정보**: OS, Node.js 버전, aiwf 버전 등
+1. **Search First**: Check if already answered
+2. **Be Specific**: Provide concrete situations over vague questions
+3. **Reproducible Example**: Include minimal reproducible example
+4. **Environment Info**: OS, Node.js version, aiwf version
 
-### 답변하기
+### Answering Questions
 
-다른 기여자의 질문에 답변할 때:
+When answering others' questions:
 
-1. **친절하게**: 초보자도 이해하기 쉽게 설명
-2. **정확하게**: 확실하지 않다면 "잘 모르겠다"고 솔직히 말하기
-3. **완전하게**: 부분적인 답변보다는 완전한 해결책 제시
+1. **Be Kind**: Explain in beginner-friendly terms
+2. **Be Accurate**: Say "I don't know" if unsure
+3. **Be Complete**: Provide complete solutions over partial answers
 
-## 릴리스 과정
+## Release Process
 
-### 버전 관리
+### Version Management
 
-aiwf는 [Semantic Versioning](https://semver.org/)을 따릅니다:
+AIWF follows [Semantic Versioning](https://semver.org/):
 
-- **MAJOR**: 호환되지 않는 API 변경
-- **MINOR**: 기존 기능과 호환되는 새로운 기능
-- **PATCH**: 기존 기능과 호환되는 버그 수정
+- **MAJOR**: Incompatible API changes
+- **MINOR**: Backward-compatible new features
+- **PATCH**: Backward-compatible bug fixes
 
-### 릴리스 일정
+### Release Schedule
 
-- **메이저 릴리스**: 필요에 따라 (Breaking changes)
-- **마이너 릴리스**: 월 1회 또는 주요 기능 완성 시
-- **패치 릴리스**: 중요한 버그 수정 시 수시로
+- **Major Releases**: As needed (breaking changes)
+- **Minor Releases**: Monthly or when major features complete
+- **Patch Releases**: As needed for important bug fixes
 
-## 도구 및 리소스
+## Tools and Resources
 
-### 개발 도구
+### Development Tools
 
-- **IDE**: VS Code, Cursor, Windsurf (Claude Code 지원)
-- **터미널**: 현대적인 터미널 (zsh, fish 등)
-- **Git GUI**: SourceTree, GitHub Desktop 등 (선택사항)
+- **IDE**: VS Code, Cursor, Windsurf (Claude Code support)
+- **Terminal**: Modern terminal (zsh, fish, etc.)
+- **Git GUI**: SourceTree, GitHub Desktop (optional)
 
-### 학습 리소스
+### Learning Resources
 
-- [Node.js 공식 문서](https://nodejs.org/docs/)
-- [Jest 테스팅 가이드](https://jestjs.io/docs/getting-started)
+- [Node.js Official Docs](https://nodejs.org/docs/)
+- [Jest Testing Guide](https://jestjs.io/docs/getting-started)
 - [Conventional Commits](https://www.conventionalcommits.org/)
 - [GitHub Flow](https://guides.github.com/introduction/flow/)
 
-## 인정과 감사
+## Recognition and Thanks
 
-기여해 주신 모든 분들께 감사드립니다! 주요 기여자들은 다음에서 확인할 수 있습니다:
+Thank you to all contributors! Key contributors can be found at:
 
-- [Contributors 페이지](https://github.com/aiwf/aiwf/graphs/contributors)
-- [릴리스 노트](https://github.com/aiwf/aiwf/releases)에서 각 릴리스별 기여자 언급
+- [Contributors page](https://github.com/aiwf/aiwf/graphs/contributors)
+- [Release notes](https://github.com/aiwf/aiwf/releases) mention contributors per release
 
 ---
 
-궁금한 점이 있으시면 언제든지 [이슈를 생성](https://github.com/aiwf/aiwf/issues/new)하거나 [토론](https://github.com/aiwf/aiwf/discussions)에 참여해 주세요!
+If you have questions, feel free to [create an issue](https://github.com/aiwf/aiwf/issues/new) or join the [discussions](https://github.com/aiwf/aiwf/discussions)!
 
-함께 더 나은 aiwf를 만들어 나가요! 🚀
+Let's build a better AIWF together! 🚀