aiwf 0.1.0 → 0.3.0

package/{PRD.ko.md → docs/PRD.ko.md}

@@ -1,10 +1,10 @@
-# HelloMoonklabs - Moonklabs 프레임워크 설치 프로그램
+# HelloAIWF - AIWF 프레임워크 설치 프로그램
 
 _버전: 0.1.0_
 
 ## 개요
 
-모든 프로젝트에 Moonklabs 프로젝트 관리 프레임워크를 설치하기 위한 최소한의 `npx` 실행 가능 커맨드 라인 도구입니다. 구조화된 디렉토리 레이아웃과 효율적인 프로젝트 관리를 위한 커맨드 라인 도구를 제공하며, 사용자 인터페이스는 한국어로 현지화되어 있습니다.
+모든 프로젝트에 AIWF 프로젝트 관리 프레임워크를 설치하기 위한 최소한의 `npx` 실행 가능 커맨드 라인 도구입니다. 구조화된 디렉토리 레이아웃과 효율적인 프로젝트 관리를 위한 커맨드 라인 도구를 제공하며, 사용자 인터페이스는 한국어로 현지화되어 있습니다.
 
 ## 핵심 기능
 
@@ -13,25 +13,25 @@ _버전: 0.1.0_
 이 도구는 `npx`를 통해 실행됩니다:
 
 ```bash
-npx hello-moonklabs
+npx hello-aiwf
 ```
 
 ### 주요 특징
 
 1.  **디렉토리 구조 생성**:
 
-    - 문서, 요구사항, 스프린트 등을 위한 표준화된 하위 디렉토리를 포함하는 `.moonklabs/` 디렉토리를 초기화합니다.
-    - 사용자 지정 Claude 명령어를 위한 `.claude/commands/moonklabs/` 디렉토리를 설정합니다.
+    - 문서, 요구사항, 스프린트 등을 위한 표준화된 하위 디렉토리를 포함하는 `.aiwf/` 디렉토리를 초기화합니다.
+    - 사용자 지정 Claude 명령어를 위한 `.claude/commands/aiwf/` 디렉토리를 설정합니다.
 
 2.  **GitHub에서 파일 가져오기**:
 
-    - GitHub의 `moonklabs/aiwf` 리포지토리에서 최신 프레임워크 파일을 다운로드합니다.
-    - 특히 `claude-code/moonklabs/` 하위 디렉토리에서 파일을 가져옵니다.
+    - GitHub의 `aiwf/aiwf` 리포지토리에서 최신 프레임워크 파일을 다운로드합니다.
+    - 특히 `claude-code/aiwf/` 하위 디렉토리에서 파일을 가져옵니다.
     - 명령어, 문서 템플릿, 프로젝트 매니페스트를 설치합니다.
 
 3.  **기존 설치 처리**:
 
-    - Moonklabs 프레임워크가 이미 존재하는지 감지합니다.
+    - AIWF 프레임워크가 이미 존재하는지 감지합니다.
     - 사용자에게 **업데이트**, **건너뛰기**, 또는 **취소**를 요청합니다.
     - 업데이트 프로세스는 사용자가 생성한 파일(작업, 스프린트)을 보존하면서 명령어 스크립트와 `CLAUDE.md` 문서를 업데이트합니다.
     - 덮어쓴 파일은 `.bak` 확장자로 자동 백업합니다.
@@ -70,7 +70,7 @@ aiwf/
 ├── claude-code/
 │   ├── docker/
 │   │   └── Dockerfile
-│   ├── moonklabs/
+│   ├── aiwf/
 │   └── simone/
 │       ├── CHANGELOG.md
 │       ├── LICENSE

package/{PRD.md → docs/PRD.md}

@@ -1,12 +1,12 @@
 [Read in Korean (한국어로 보기)](PRD.ko.md)
 
-# HelloMoonklabs - Installer for Moonklabs Framework
+# HelloAIWF - Installer for AIWF Framework
 
 _Version: 0.1.0_
 
 ## Overview
 
-A minimal, `npx`-executable command-line tool to install the Moonklabs project management framework into any project. It provides a structured directory layout and command-line tools for streamlined project management, with a user interface localized in Korean.
+A minimal, `npx`-executable command-line tool to install the AIWF project management framework into any project. It provides a structured directory layout and command-line tools for streamlined project management, with a user interface localized in Korean.
 
 ## Core Functionality
 
@@ -15,25 +15,25 @@ A minimal, `npx`-executable command-line tool to install the Moonklabs project m
 The tool is executed via `npx`:
 
 ```bash
-npx hello-moonklabs
+npx hello-aiwf
 ```
 
 ### Key Features
 
 1.  **Creates Directory Structure**:
 
-    - Initializes the `.moonklabs/` directory with standardized subdirectories for documents, requirements, sprints, and more.
-    - Sets up the `.claude/commands/moonklabs/` directory for custom Claude commands.
+    - Initializes the `.aiwf/` directory with standardized subdirectories for documents, requirements, sprints, and more.
+    - Sets up the `.claude/commands/aiwf/` directory for custom Claude commands.
 
 2.  **Fetches from GitHub**:
 
-    - Downloads the latest framework files from the `moonklabs/aiwf` repository on GitHub.
-    - Specifically, it sources files from the `claude-code/moonklabs/` subdirectory.
+    - Downloads the latest framework files from the `aiwf/aiwf` repository on GitHub.
+    - Specifically, it sources files from the `claude-code/aiwf/` subdirectory.
     - Installs commands, documentation templates, and the project manifest.
 
 3.  **Handles Existing Installations**:
 
-    - Detects if a Moonklabs framework is already present.
+    - Detects if a AIWF framework is already present.
     - Prompts the user to **Update**, **Skip**, or **Cancel**.
     - The update process preserves user-created files (tasks, sprints) while updating command scripts and `CLAUDE.md` documents.
     - Automatically backs up overwritten files with a `.bak` extension.
@@ -72,7 +72,7 @@ aiwf/
 ├── claude-code/
 │   ├── docker/
 │   │   └── Dockerfile
-│   ├── moonklabs/
+│   ├── aiwf/
 │   └── simone/
 │       ├── CHANGELOG.md
 │       ├── LICENSE

package/docs/moonklabs-metadata-system-prd.md

@@ -0,0 +1,127 @@
+# AIWF 메타데이터 관리 시스템 PRD
+
+_(GitHub Issue 사용 옵션형 — 미사용 시에도 동작하도록 설계)_
+
+## 목차
+
+1. 제품 개요
+2. 참고 서비스 및 도입 근거
+3. 핵심 기능 및 상세 사양
+4. 추가 제안 기능
+5. 타깃 유저 페르소나 & 사용 시나리오
+6. 기술 스택 제안
+7. 부록 – 저장·동기화 전략(옵션별)
+
+---
+
+## 1. 제품 개요
+
+> **문제**  
+> AIWF 프로젝트는 마일스톤·스프린트·태스크 정보를 Markdown 파일에 분산 저장한다. 여러 사람이 동시 작업할 때  
+> • 어떤 ID가 이미 존재하는지  
+> • 누가 어떤 태스크를 맡았는지  
+> • 상태가 최신인지  
+> 를 파악하기 위해 매번 디렉터리를 전수 검색해야 한다.
+
+> **해결**  
+> `index.json` 단일 진실 소스(SSOT)를 자동 생성·검증하고, **Git 브랜치 + 잠금 필드**로 동시 편집 충돌을 차단한다.  
+> GitHub Issue 연동은 **옵션**으로 제공하여, 오프라인·사내 Git 서버에서도 동일한 워크플로를 유지한다.
+
+---
+
+## 2. 참고 서비스 및 도입 근거
+
+| 레퍼런스 서비스        | 핵심 기능                        | 도입 근거                                          |
+| ---------------------- | -------------------------------- | -------------------------------------------------- |
+| **GitHub Projects V2** | 칸반·타임라인 · Issue/PR 연동    | GitHub 저장소 기반 협업일 때 시각화·알림이 우수    |
+| **Atlassian Jira**     | 워크플로/상태 전이 · 강력한 필터 | 대규모 팀이 복잡한 워크플로를 모델링하는 사례 참고 |
+| **Notion Database**    | 자유로운 속성 추가 · 뷰 전환     | Markdown 유사 환경 + 메타데이터 확장성 참고        |
+| **Linear**             | 빠른 키보드 UX · 흐름 최소화     | 개발자 생산성을 높이는 경량 UI 아이디어 차용       |
+
+---
+
+## 3. 핵심 기능 및 상세 사양
+
+| 분류                | 기능                        | 사양                                                                                     |
+| ------------------- | --------------------------- | ---------------------------------------------------------------------------------------- |
+| 메타데이터          | **index.json 생성**         | `npm run aiwf:sync` → Markdown front-matter 파싱 후 마일스톤·스프린트·태스크 맵 생성     |
+| 검증                | **validate-index**          | 중복 ID, 잠금 충돌, 규칙 위반 CI 차단<br/>`npm run validate-index` & GitHub Actions      |
+| 동시 작업           | **lockedBy 필드**           | `moon lock TS01` → `lockedBy`·`lockTime` 기록, 병행 작업 충돌 시 git merge conflict 유도 |
+| Git 통합            | **브랜치 네이밍 규칙**      | `feat/MS01-SP02-implement-login-api` 식으로 범위 명시                                    |
+| CI/CD               | **validate-index.yml**      | PR 시 `aiwf:sync` → `validate-index` 자동 실행                                           |
+| CLI                 | **moon lock/unlock** (단축) | commander 기반 CLI; 잠금/해제 & 상태 변경                                                |
+| 옵션형 GitHub Issue | **Issue ↔ index 싱크**      | (선택) `moon sync issues` 커맨드: Issue Label ↔ ID 매핑 후 index 갱신                    |
+
+### 데이터 스키마 요약
+
+```jsonc
+{
+  "tasks": {
+    "TS01": {
+      "type": "task", // task|sprint|milestone
+      "status": "in-progress",
+      "sprint": "SP01",
+      "milestone": "MS01",
+      "lockedBy": "drumcap", // null ⇒ free
+      "lockTime": "2025-06-29T08:15:03Z"
+    }
+  }
+}
+```
+
+---
+
+## 4. 추가 제안 기능
+
+| 기능                | 설명                                         | 기대 효과                               |
+| ------------------- | -------------------------------------------- | --------------------------------------- |
+| VSCode 확장         | `index.json` 시각화 Tree View + 잠금 UI      | 실시간 상태 확인 & 클릭 한 번 잠금/해제 |
+| 간트 차트 HTML      | `moon gantt` 명령으로 HTML 산출              | 프로젝트 진행률 리포트 공유             |
+| Git pre-commit hook | 자동 `sync` & `validate` → 실패 시 커밋 차단 | 규칙 위반 사전 방지                     |
+| Slack/Bot 알림      | 태스크 락/언락, 상태 변경 시 알림            | 투명한 협업, 병렬 작업 충돌 최소화      |
+
+---
+
+## 5. 타깃 유저 페르소나 & 사용 시나리오
+
+| 페르소나          | 목표                          | Pain Point                            |
+| ----------------- | ----------------------------- | ------------------------------------- |
+| **Backend Dev A** | API 기능 구현 완료 후 빠른 PR | 누가 같은 태스크 작업 중인지 불명확   |
+| **PM B**          | 스프린트 진척률 리포트        | 여러 Markdown 파일을 열어 진척률 합산 |
+| **DevOps C**      | CI 실패 최소화                | 메타데이터 오류로 PR 병합 지연        |
+
+### 핵심 시나리오 ① — 개발자 작업 예약
+
+1. `moon lock TS14`로 태스크 잠금
+2. 기능 개발 후 `moon unlock TS14 --status=done`
+3. PR → CI 통과 → 병합
+
+### 핵심 시나리오 ② — PM 진척률 확인
+
+1. `moon gantt --export`
+2. HTML 레포트 Slack 공유 → 팀 회의에서 진행 상황 검토
+
+---
+
+## 6. 기술 스택 제안
+
+| 범주   | 선택                                                         | 비고                           |
+| ------ | ------------------------------------------------------------ | ------------------------------ |
+| 런타임 | **Node.js ≥18**                                              | ES Module, async fs            |
+| 언어   | **TypeScript** (추가 권장)                                   | 타입 안전, CLI/라이브러리 공유 |
+| 패키지 | `commander`, `ora`, **`gray-matter`**, **`fast-glob`**       | front-matter 파싱 & 파일 찾기  |
+| CI     | **GitHub Actions**                                           | PR 검증 · 배포 파이프라인      |
+| 저장   | **Markdown + index.json** (기본)<br/>**GitHub Issue** (옵션) | 오프라인 OK / 클라우드 확장    |
+| 배포   | npm package (`aiwf-cli`)                                     | 사내 NPM 레지스트리 배포 가능  |
+
+---
+
+## 7. 부록 – 저장·동기화 전략
+
+| 시나리오            | 기본 동작                                   | GitHub Issue 미사용 시     |
+| ------------------- | ------------------------------------------- | -------------------------- |
+| **로컬 오프라인**   | Markdown edit → `sync-index` → `index.json` | 동일 – 모든 기능 100% 동작 |
+| **GitHub PR**       | CI `validate-index` → PR 머지               | 동일 – Issue API 호출 생략 |
+| **Issue 연동 필요** | `moon sync issues` → Label ↔ ID 매핑        | (사용 안 함) 옵션 스킵     |
+
+> ⚠️ **GitHub Issue 연동은 전 과정에서 선택적**이며, 미사용 시에도 동시 편집 차단·진척률 통계 등 핵심 기능은 그대로 제공됩니다.