refactor: .agents + .agent 단일 .agent 디렉토리로 통합 (agent_guide 포맷, 12→7 워크플로우 축소)

2026-03-11 01:02:33 +09:00
parent d50d3d86af
commit acc8533ef2
26 changed files with 300 additions and 763 deletions
--- a/.agent/AGENT.md
+++ b/.agent/AGENT.md
@@ -0,0 +1,54 @@
+---
+description: 모든 작업에 자동 적용되는 에이전트 행동 규칙. 새 대화 시작 시 반드시 이 파일을 먼저 읽습니다.
+---
+
+# Agent Rules
+
+## Identity
+
+당신은 이 프로젝트의 시니어 개발자입니다. 지시를 정확히 따르고, 추측보다 근거를 우선합니다.
+
+## NEVER (절대 금지)
+
+1. NEVER start coding without reading relevant reference documents in `.agent/references/`
+2. NEVER guess when documentation exists — always check `.agent/references/` first
+3. NEVER repeat a failed approach — check `.agent/references/known-issues.md` first
+4. NEVER call APIs directly when helper scripts exist in `.agent/workflows/helpers/`
+5. NEVER skip the pre-task checklist defined in `.agent/workflows/pre-task.md`
+6. NEVER attempt the same failed approach more than 2 times
+7. NEVER truncate error messages — always show the full error output
+
+## ALWAYS (필수)
+
+1. ALWAYS run `.agent/workflows/pre-task.md` before any implementation task
+2. ALWAYS check `.agent/references/known-issues.md` before debugging
+3. ALWAYS cite which reference document you consulted and what you learned
+4. ALWAYS stop and ask the user if 2 consecutive attempts on the same approach fail
+5. ALWAYS use existing helper scripts instead of raw API calls
+6. ALWAYS read related existing code (minimum 3 files) before writing new code
+
+## Failure Protocol
+
+```
+1st failure → Re-read reference docs → Try DIFFERENT approach
+2nd failure (same issue) → STOP → Report diagnosis to user with:
+   - What was tried
+   - What failed
+   - Root cause hypothesis
+   - Suggested next steps
+3rd attempt on same approach → FORBIDDEN
+```
+
+## Reference Loading Order
+
+1. `.agent/AGENT.md` (this file — behavior rules)
+2. `.agent/references/known-issues.md` (past failure patterns)
+3. `.agent/references/` (project-specific knowledge)
+4. `.agent/workflows/services.md` (service credentials & protocols)
+5. `.agent/workflows/` (action procedures)
+
+## PowerShell Notes
+
+- `curl` → PowerShell에서 `Invoke-WebRequest` 별칭. **반드시 `curl.exe`** 사용
+- `npm` → 실행 정책 문제 시 `cmd /c npm` 사용
+- JSON 처리 시 `.py` 스크립트 권장 (PowerShell 이스케이핑 이슈 방지)
--- a/.agent/GUIDE.md
+++ b/.agent/GUIDE.md
@@ -0,0 +1,154 @@
+# AI 에이전트 워크플로우 시스템 가이드
+
+> 이 가이드는 AI 코딩 에이전트가 더 똑똑하게 동작하도록 설계된 범용 워크플로우 시스템의 사용법을 설명합니다.
+
+---
+
+## 왜 이 시스템이 필요한가?
+
+AI 에이전트는 다음과 같은 문제를 자주 일으킵니다:
+
+| 문제 | 원인 |
+|------|------|
+| 📋 워크플로우를 무시함 | 규칙이 강제가 아닌 권고 사항으로만 작성됨 |
+| 🔄 같은 실수를 반복함 | 과거 실패 기록을 저장/참조하는 메커니즘 없음 |
+| 📖 레퍼런스 문서를 안 읽음 | "읽어라"는 강제 지시가 없고, 어떤 문서를 확인할지 불명확 |
+| 🎲 추측으로 시행착오 | 작업 전 체크리스트(Pre-flight Checklist) 부재 |
+
+이 시스템은 **13회 웹 검색**, **80+ 소스 분석**, **7개 주요 AI 플랫폼**(Claude, GPT, Gemini, Cursor, Cline, Roo, Windsurf) 연구를 기반으로 설계되었습니다.
+
+---
+
+## 파일 구조 개요
+
+```
+.agent/
+├── AGENT.md                          ← 🧠 에이전트 헌법 (NEVER/ALWAYS 규칙)
+├── GUIDE.md                          ← 📖 이 가이드
+├── references/                       ← 📚 프로젝트 지식 베이스
+│   ├── architecture.md               ← 아키텍처 설명
+│   ├── tech-stack.md                 ← 기술 스택 & 버전
+│   ├── conventions.md                ← 코딩 컨벤션
+│   └── known-issues.md               ← 🔴 과거 실패 기록 (핵심!)
+└── workflows/                        ← ⚙️ 행동 절차
+    ├── start.md                      ← 세션 시작 (룰 로딩 + devlog 복구)
+    ├── end.md                        ← 세션 종료 (devlog + known-issues + Vikunja + Git)
+    ├── pre-task.md                   ← 작업 전 필수 체크리스트
+    ├── debug.md                      ← 디버깅 전용 절차
+    ├── services.md                   ← 서비스 연동 + 작업 프로토콜 + 개발/테스트 명령어
+    ├── check-gitea.md                ← Gitea 현황 조회
+    ├── check-vikunja.md              ← Vikunja 태스크 조회
+    └── helpers/
+        ├── vikunja_helper.py         ← Vikunja API 안전 래퍼
+        └── wiki_helper.py            ← Gitea Wiki 래퍼
+```
+
+**프로젝트 루트에 자동 생성되는 디렉토리:**
+```
+docs/devlog/                          ← 📓 세션별 작업 기록
+├── YYYY-MM-DD.md                     ← Index (매일 1줄씩 누적)
+└── entries/
+    └── YYYYMMDD-NNN.md               ← Entry (설계 결정/미완료 시만)
+```
+
+---
+
+## 각 파일의 역할
+
+### 🧠 `AGENT.md` — 에이전트 헌법
+
+에이전트가 **모든 대화에서 따라야 하는 글로벌 규칙**입니다.
+
+**핵심 메커니즘:**
+- **NEVER 규칙**: `"절대 ~하지 마라"` — 연구에 따르면 금지 규칙이 더 잘 지켜집니다
+- **Failure Protocol**: 동일 접근 2회 실패 시 자동 중단 → 유저에게 보고
+- **Reference Loading Order**: 어떤 문서를 먼저 읽을지 우선순위 명시
+
+### 📋 `pre-task.md` — 사전 점검 체크리스트
+
+모든 구현 작업 전에 실행하는 **4단계 체크리스트**:
+1. 요구사항 정리
+2. 레퍼런스 확인 (추측 금지)
+3. 계획 수립
+4. 유저 확인
+
+### 🔴 `known-issues.md` — 과거 실패 기록
+
+**가장 중요한 파일.** 에이전트가 같은 실수를 반복하는 근본 원인은 **실패를 기억하지 못하기 때문**입니다. 이 파일은:
+- 세션 종료 시 에이전트가 자동으로 새 이슈를 추가
+- 디버깅/구현 전에 에이전트가 반드시 확인
+- 시간이 지날수록 **축적 학습** 효과
+
+### 🔧 `debug.md` — 디버깅 전용 워크플로우
+
+**추측 기반 디버깅을 금지**하는 5단계 절차:
+1. 정보 수집 (에러 전문 확인)
+2. known-issues 확인
+3. 근본 원인 분석 (가설 → 검증)
+4. 수정 및 검증
+5. 기록 (known-issues에 추가)
+
+### 📓 Devlog — 세션별 작업 기록 (start.md / end.md에서 관리)
+
+known-issues가 **실패만** 기록한다면, devlog는 **전체 세션 이력**을 기록합니다:
+- **Index** (`docs/devlog/YYYY-MM-DD.md`): 매 작업마다 1줄 (필수)
+- **Entry** (`docs/devlog/entries/YYYYMMDD-NNN.md`): 설계 결정/미완료/삽질 시만 (선택)
+- **start.md**에서 자동으로 오늘/어제 devlog를 읽어 맥락 복구
+
+### ▶️ `start.md` / ⏹️ `end.md` — 세션 관리
+
+- **start**: 에이전트 룰 로딩 + devlog 맥락 복구 + Git 상태 + Vikunja TODO
+- **end**: known-issues 업데이트 + devlog 기록 + Vikunja 동기화 + Git commit/push
+
+---
+
+## 사용법
+
+### 프로젝트별 워크플로우와 함께 사용하기
+
+이 범용 워크플로우와 프로젝트별 워크플로우(예: Vikunja 동기화, Gitea 연동)는 **함께 사용**합니다:
+
+```
+.agent/
+├── AGENT.md                    ← 범용 (공통)
+├── references/                 ← 범용 + 프로젝트 특화
+│   ├── known-issues.md         ← 범용 (공통)
+│   └── ...                     ← 프로젝트에 맞게 작성
+└── workflows/
+    ├── pre-task.md             ← 범용 (공통)
+    ├── debug.md                ← 범용 (공통)
+    ├── start.md                ← 범용 기반 + 프로젝트 단계 추가
+    ├── end.md                  ← 범용 기반 + 프로젝트 단계 추가
+    ├── services.md             ← ⭐ 프로젝트별 (서비스 + 프로토콜 + 개발/테스트)
+    ├── check-vikunja.md        ← ⭐ 프로젝트별
+    ├── check-gitea.md          ← ⭐ 프로젝트별
+    └── helpers/
+        ├── vikunja_helper.py   ← ⭐ 프로젝트별
+        └── wiki_helper.py      ← ⭐ 프로젝트별
+```
+
+### 다른 AI IDE에서도 사용하기
+
+| 대상 플랫폼 | 방법 |
+|------------|------|
+| **Cursor** | `AGENT.md` → `.cursor/rules/agent.mdc` (alwaysApply) |
+| **Claude Code** | `AGENT.md` → `CLAUDE.md`, references를 `@import` |
+| **Windsurf** | `AGENT.md` → `.windsurfrules` 또는 `.windsurf/rules/agent.md` |
+| **Cline/Roo** | 루트에 `AGENTS.md`로 복사 |
+| **Gemini** | `AGENT.md` → `.gemini/GEMINI.md` |
+
+---
+
+## 연구 근거 요약
+
+이 시스템의 각 설계 결정은 학술 연구와 실무 사례에 근거합니다:
+
+| 설계 결정 | 근거 |
+|----------|------|
+| NEVER > ALWAYS (금지 규칙 우선) | Community 검증 — "NEVER use X" ≫ "always prefer Y" |
+| 2회 실패 시 자동 중단 | Streak Breaker / Sentinel Check 연구 |
+| 실패 기록 누적 | Reflexion Framework (텍스트 피드백 기반 자기 교정) |
+| 사전 체크리스트 강제 | Claude Skills 체크리스트 + GPT Chain-of-Thought |
+| Progressive Disclosure | Anthropic Context Engineering (2025) |
+| 300줄 이하 규칙 | Claude `CLAUDE.md` 공식 권장 (토큰 효율성) |
+| 코드 예시 > 설명 | GitHub Copilot Agents, AGENTS.md 공통 Best Practice |
--- a/.agent/references/architecture.md
+++ b/.agent/references/architecture.md
@@ -0,0 +1,75 @@
+# Architecture
+
+> Variet Agent — Gemini CLI 기반 AI Agent Team 시스템
+
+## 프로젝트 개요
+
+사용자가 디스코드에서 자연어 명령 → AI Agent Team이 코드 분석/분해/실행 → Gitea CI로 PR/빌드/배포.
+Gemini CLI를 서브프로세스(`asyncio.create_subprocess_exec`)로 래핑하여 역할별 독립 컨텍스트로 호출.
+
+## 디렉토리 구조
+
+```
+variet-agent/
+├── main.py                  # 진입점 (FastAPI + Discord Bot 동시 실행)
+├── config.py                # .env 기반 설정 관리
+├── api/
+│   ├── server.py            # FastAPI REST 서버
+│   ├── discord_bot.py       # Discord Bot (NLU + PCRS 파이프라인 + 애니 핸들러)
+│   └── models.py            # 요청/응답 모델
+├── core/
+│   ├── task_pipeline.py     # PCRS: Plan → Code → Review → Summarize
+│   ├── gemini_caller.py     # Gemini CLI 래퍼 (text/agent 모드)
+│   ├── context_manager.py   # 관련 파일 선별 + 토큰 예산 제어
+│   ├── project_indexer.py   # 프로젝트 구조 스캔/캐시
+│   ├── workspace.py         # 워크스페이스 관리 (채널 ↔ 프로젝트 매핑)
+│   ├── file_applier.py      # 코드 변경 적용
+│   └── docs_manager.py      # 문서/세션 기록
+├── tools/                   # 자동화 도구 (애니메이션 파이프라인)
+│   ├── anime_pipeline.py    # 통합 파이프라인 (검색/다운/자막/상태)
+│   ├── anissia_client.py    # Anissia 편성표 API
+│   ├── nyaa_client.py       # Nyaa 토렌트 검색
+│   ├── qbit_client.py       # qBittorrent 제어
+│   ├── nas_scanner.py       # NAS 파일 스캔
+│   ├── title_matcher.py     # 제목 매칭 (로마지/퍼지)
+│   └── subtitle_downloader.py  # 자막 다운로더
+├── integrations/
+│   ├── gitea_client.py      # Gitea API (PR/이슈)
+│   ├── vikunja_client.py    # Vikunja 태스크 관리
+│   └── ci_monitor.py        # CI 결과 모니터링
+└── prompts/                 # AI 역할별 프롬프트
+    ├── unified.md           # NLU 분류 (chat/task/anime/clarify)
+    ├── planner.md           # 태스크 분해
+    ├── coder.md             # 코드 구현
+    ├── reviewer.md          # 코드 리뷰
+    └── summarizer.md        # 총평 생성
+```
+
+## 핵심 모듈
+
+| 모듈 | 역할 | 의존성 |
+|------|------|--------|
+| `discord_bot.py` | 사용자 인터페이스 + NLU 분류 | `workspace.py`, `gemini_caller.py`, `task_pipeline.py` |
+| `task_pipeline.py` | PCRS 오케스트레이션 (Inner/Outer 루프) | `gemini_caller.py`, `context_manager.py`, `project_indexer.py` |
+| `gemini_caller.py` | Gemini CLI 서브프로세스 호출 (text/agent) | `prompts/` |
+| `context_manager.py` | 태스크 기반 파일 선별 + 토큰 예산 | `project_indexer.py` |
+| `workspace.py` | 채널 ↔ 프로젝트 경로 매핑, workspaces.json 관리 | — |
+| `anime_pipeline.py` | 애니 자동화 통합 | `anissia_client.py`, `nyaa_client.py`, `qbit_client.py`, `nas_scanner.py` |
+
+## 데이터 흐름
+
+```
+Discord 메시지
+  → on_message()
+    → _unified_call() — NLU 분류 (chat/task/anime/clarify)
+      ├─ chat → 즉답
+      ├─ clarify → 질문 임베드
+      ├─ anime → _handle_anime() → AnimePipeline
+      └─ task → _handle_task()
+            → TaskPipeline.plan() — Planner (태스크 분해)
+            → TaskPipeline.code_parallel() — Coder (에이전트 모드, cwd=프로젝트)
+            → TaskPipeline.planner_verify() — 내부 자가검증 (Inner Loop)
+            → TaskPipeline.batch_review() — Reviewer (Outer Loop)
+            → TaskPipeline.summarize() — 총평
+            → Discord Embed 보고
+```
--- a/.agent/references/conventions.md
+++ b/.agent/references/conventions.md
@@ -0,0 +1,45 @@
+# Coding Conventions
+
+> AI 에이전트는 코드를 작성하기 전 이 컨벤션을 확인합니다.
+
+## 네이밍
+
+| 대상 | 규칙 | 예시 |
+|------|------|------|
+| 변수/함수 | camelCase | `getUserData()` |
+| 클래스 | PascalCase | `UserService` |
+| 상수 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
+| 파일명 | kebab-case | `user-service.js` |
+| CSS 클래스 | kebab-case | `.nav-header` |
+
+## 코드 스타일
+
+- 들여쓰기: (2 spaces / 4 spaces / tab)
+- 세미콜론: (사용 / 미사용)
+- 따옴표: (single / double)
+- 줄바꿈: LF (Unix style)
+
+## 커밋 메시지
+
+```
+<type>(<scope>): <description>
+
+type: feat|fix|refactor|test|docs|chore|ci|infra
+scope: (선택)
+```
+
+**예시:**
+- `feat(server): add WebSocket reconnection logic`
+- `fix(frontend): resolve button overlap on mobile`
+- `docs: update API documentation`
+
+## 주석
+
+- 한국어/영어 혼용 가능
+- TODO 주석: `// TODO: 설명` 형식
+- 복잡한 로직에는 반드시 WHY(왜) 주석 추가
+
+## 테스트
+
+- 테스트 파일 위치: (예: `__tests__/` 또는 `*.test.js`)
+- 테스트 네이밍: `should [expected behavior] when [condition]`
--- a/.agent/references/known-issues.md
+++ b/.agent/references/known-issues.md
@@ -0,0 +1,59 @@
+# Known Issues & Lessons Learned
+
+> **이 파일은 SSOT(Single Source of Truth)입니다.**
+> 디버깅이나 구현 전에 **반드시** 이 파일을 확인하세요.
+> 세션 종료 시 새로 발견된 이슈를 이 파일에 추가합니다.
+
+---
+
+## 포맷
+
+각 항목은 아래 형식을 따릅니다:
+
+```markdown
+### [날짜] [키워드] — 한줄 요약
+- **증상**: 무엇이 잘못되었는가
+- **원인**: 근본 원인
+- **해결**: 올바른 해결 방법
+- **주의**: 재발 방지를 위한 교훈
+```
+
+---
+
+## 공통 이슈
+
+### [2026-03-08] PowerShell curl — Invoke-WebRequest 충돌
+- **증상**: `curl` 명령이 예상과 다른 응답 형식을 반환
+- **원인**: PowerShell에서 `curl`은 `Invoke-WebRequest`의 별칭
+- **해결**: **`curl.exe`**를 명시적으로 사용
+- **주의**: HTTP 관련 모든 명령에서 `curl.exe` 사용 필수
+
+### [2026-03-08] PowerShell npm — 실행 정책 오류
+- **증상**: `npm run` 명령이 `실행 정책` 관련 오류로 실패
+- **원인**: PowerShell 스크립트 실행 정책이 제한적으로 설정됨
+- **해결**: `cmd /c npm run dev` 형식으로 cmd를 통해 실행
+- **주의**: npm 관련 명령은 항상 `cmd /c` 접두어 사용 권장
+
+---
+
+## 프로젝트별 이슈
+
+> 아래에 프로젝트 특화 이슈를 추가하세요.
+
+### [2026-03-08] nas_scanner docstring — Unicode escape SyntaxError
+- **증상**: `from tools.nas_scanner import NasScanner` 시 `SyntaxError: (unicode error) 'unicodeescape' codec can't decode \N`
+- **원인**: docstring 내 `\\NasData` 경로에서 `\N`이 Python Unicode named escape로 해석
+- **해결**: docstring을 `r"""..."""` (raw string)으로 변경
+- **주의**: Windows 경로(`\\`, `\N`, `\U` 등)가 포함된 docstring은 반드시 `r"""`로 작성
+
+### [2026-03-08] title_matcher _kata_to_hira — 장음기호 깨짐
+- **증상**: `フリーレン` → `ふり゜れん` (ー가 ゜로 변환)
+- **원인**: 카타카나 범위 `0x30A0~0x30FF`에 기호 문자(`ー` U+30FC) 포함
+- **해결**: 범위를 `0x30A1~0x30F6`으로 좁혀 실제 문자만 변환
+- **주의**: 유니코드 범위 지정 시 기호/구두점 문자 포함 여부 확인 필수
+
+### [2026-03-08] anime_pipeline — Nyaa 검색 0건 반환
+- **증상**: 한자 포함 원제의 로마자 변환 결과(`葬送nofuriren`) + suffix 고정으로 Nyaa 검색 실패
+- **원인**: 단일 검색 전략, suffix(ASW HEVC) 항상 부착
+- **해결**: 6단계 fallback 전략 (romaji±suffix → 원제±suffix → 한글±suffix)
+- **주의**: 외부 API 검색 시 반드시 다중 전략 + suffix 토글 구현
--- a/.agent/references/tech-stack.md
+++ b/.agent/references/tech-stack.md
@@ -0,0 +1,59 @@
+# Tech Stack
+
+> AI 에이전트는 구현 전 이 문서를 확인하여 올바른 기술/버전을 사용합니다.
+
+## 언어 & 런타임
+
+| 항목 | 버전 | 비고 |
+|------|------|------|
+| Python | 3.12+ | `C:\ProgramData\miniforge3\envs\variet-agent\python.exe` |
+| Gemini CLI | v0.32+ (AI Ultra) | `gemini --model gemini-3-flash-preview` |
+
+## 프레임워크
+
+| 항목 | 버전 | 용도 |
+|------|------|------|
+| FastAPI | 최신 | REST API 서버 |
+| discord.py | 2.x | Discord Bot |
+| uvicorn | 최신 | ASGI 서버 |
+| httpx | 최신 | 비동기 HTTP 클라이언트 (tools/) |
+
+## 패키지 관리
+
+- 패키지 매니저: pip (conda env `variet-agent`)
+- 의존성 파일: `requirements.txt`
+- 가상환경: `C:\ProgramData\miniforge3\envs\variet-agent`
+
+## 개발 도구
+
+| 도구 | 명령어 |
+|------|--------|
+| 봇 실행 | `run_bot.bat` 또는 `C:\ProgramData\miniforge3\envs\variet-agent\python.exe main.py` |
+| 테스트 | `C:\ProgramData\miniforge3\envs\variet-agent\python.exe -m pytest tests/ -v` |
+| Vikunja 조회 | `C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py list todo` |
+
+## 환경 변수 (.env)
+
+| 변수명 | 용도 | 기본값 |
+|--------|------|--------|
+| DISCORD_BOT_TOKEN | Discord 봇 토큰 | (필수) |
+| API_HOST | API 서버 호스트 | 0.0.0.0 |
+| API_PORT | API 서버 포트 | 8000 |
+| GITEA_URL | Gitea 서버 | https://git.variet.net |
+| GITEA_TOKEN | Gitea API 토큰 | (필수) |
+| GITEA_REPO | Gitea 저장소 | Variet/variet-agent |
+| VIKUNJA_URL | Vikunja 서버 | https://plan.variet.net |
+| VIKUNJA_TOKEN | Vikunja API 토큰 | (필수) |
+| VIKUNJA_PROJECT_ID | Vikunja 프로젝트 ID | 7 |
+| QBIT_URL | qBittorrent URL | http://localhost:8080 |
+| NAS_ANIME_PATH | NAS 애니 경로 | \\\\192.168.10.10\NasData\Video\Animation |
+
+## 외부 서비스
+
+| 서비스 | URL | 용도 |
+|--------|-----|------|
+| Gitea | git.variet.net | Git 저장소, PR, CI |
+| Vikunja | plan.variet.net | 태스크 관리 (프로젝트 #7) |
+| Anissia | anissia.net | 애니 편성표/자막 |
+| Nyaa | nyaa.si | 토렌트 검색 |
+| qBittorrent | localhost:8080 | 토렌트 다운로드 |
--- a/.agent/workflows/check-gitea.md
+++ b/.agent/workflows/check-gitea.md
@@ -1,5 +1,5 @@
 ---
-description: Gitea API로 variet-agent 저장소 커밋/이슈/PR 현황을 조회하는 워크플로우
+description: Gitea API로 저장소 커밋/이슈/PR 현황을 조회하는 워크플로우
 ---

 # Gitea 저장소 현황 조회
@@ -32,7 +32,15 @@ Invoke-RestMethod -Uri "https://git.variet.net/api/v1/repos/Variet/variet-agent/

 4. Wiki 페이지 목록:
 ```powershell
-$h = @{Authorization="token 3a01b4b15a39921572e64c413353e870d4d2161b"}
-$pages = Invoke-RestMethod -Uri "https://git.variet.net/api/v1/repos/Variet/variet-agent/wiki/pages" -Headers $h
-$pages | ForEach-Object { Write-Host $_.title }
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\wiki_helper.py list
+```
+
+5. Wiki 페이지 읽기:
+```powershell
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\wiki_helper.py read "Architecture"
+```
+
+6. Wiki 페이지 업데이트:
+```powershell
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\wiki_helper.py update "페이지-제목" /tmp/wiki_content.md
 ```
--- a/.agent/workflows/check-status.md
+++ b/.agent/workflows/check-status.md
@@ -1,43 +0,0 @@
---
-description: ?„ë¡œ?<3F>íŠ¸ ?„ì²´ ?‘ì—… ?„í™©??ì¢…í•© ì²´í<C2B4>¬?˜ëŠ” ?Œí<C592>¬?Œë¡œ??(Git + Vikunja + ë¡œì»¬)
---
-
-# ?„ë¡œ?<3F>íŠ¸ ?„í™© ì¢…í•© ì²´í<C2B4>¬
-
-"?‘ì—…?<3F>í™© ì²´í<C2B4>¬", "?„í™© ?•ì<E280A2>¸", "status check" ???”ì² ?????Œí<C592>¬?Œë¡œ?°ë? ?¤í–‰?©ë‹ˆ??
-
-// turbo-all
-
-## ?ˆì°¨
-
-1. Git ë¡œì»¬ ?<3F>íƒœ ?•ì<E280A2>¸:
-```powershell
-git -C "c:\Users\Certes\Desktop\variet-agent" status --short
-```
-```powershell
-git -C "c:\Users\Certes\Desktop\variet-agent" log --oneline -5
-```
-
-2. Vikunja ?œìŠ¤???„í™© ì¡°íšŒ:
-```powershell
-$h = @{Authorization="Bearer tk_070f8e0b715e818bb7178c3815ed5389040eddca"}
-$tasks = Invoke-RestMethod -Uri "https://plan.variet.net/api/v1/projects/7/tasks?per_page=50" -Headers $h
-$todo = $tasks | Where-Object { -not $_.done }
-$done = $tasks | Where-Object { $_.done }
-Write-Host "=== Vikunja: TODO $($todo.Count), DONE $($done.Count) ==="
-$todo | ForEach-Object { Write-Host "  #$($_.id) $($_.title)" }
-```
-
-3. Gitea ìµœê·¼ ì»¤ë°‹ ?•ì<E280A2>¸ (ë¦¬ëª¨??:
-```powershell
-$h = @{Authorization="token 3a01b4b15a39921572e64c413353e870d4d2161b"}
-$commits = Invoke-RestMethod -Uri "https://git.variet.net/api/v1/repos/Variet/variet-agent/commits?limit=5&sha=main" -Headers $h
-Write-Host "=== Gitea: Recent Commits ==="
-$commits | ForEach-Object { Write-Host "  $($_.sha.Substring(0,7)) $($_.commit.message.Split("`n")[0])" }
-```
-
-4. ê²°ê³¼ë¥?ì¢…í•©?˜ì—¬ ?¬ìš©?<3F>ì—<C3AC>ê²?ë³´ê³ :
-   - ë¡œì»¬ uncommitted ë³€ê²??¬ë?
-   - ë¡œì»¬ vs ë¦¬ëª¨??ì»¤ë°‹ ì°¨ì<C2A8>´
-   - TODO ?œìŠ¤??ëª©ë¡<C3AB> + ?°ì„ ?œìœ„
-   - ?¤ì<C2A4>Œ ?‘ì—… ?œì•ˆ
--- a/.agent/workflows/check-vikunja.md
+++ b/.agent/workflows/check-vikunja.md
@@ -1,50 +1,55 @@
 ---
-description: Vikunja APIë¡?Variet Agent ?„ë¡œ?<3F>íŠ¸ ?œìŠ¤???„í™©??ì¡°íšŒ?˜ëŠ” ?Œí<C592>¬?Œë¡œ??
+description: Vikunja API로 프로젝트 태스크 현황을 조회하는 워크플로우
 ---

-# Vikunja ?œìŠ¤???„í™© ì¡°íšŒ
+# Vikunja 태스크 현황 조회

-?œë¹„???•ë³´??`.agent/workflows/services.md` ì°¸ì¡°.
+서비스 정보는 `.agent/workflows/services.md` 참조.

 // turbo-all

-## ?ˆì°¨
+## 절차

-1. ê°„íŽ¸ ì¡°íšŒ (TODO/DONE ë¦¬ìŠ¤??:
+1. 전체 목록:
 ```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agent\workflows\vikunja_helper.py list
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py list
 ```

-2. TODOë§?ì¡°íšŒ:
+2. TODO만:
 ```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agent\workflows\vikunja_helper.py list todo
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py list todo
 ```

-3. DONEë§?ì¡°íšŒ:
+3. DONE만:
 ```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agent\workflows\vikunja_helper.py list done
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py list done
 ```

-4. ?œìŠ¤???„ë£Œ ì²˜ë¦¬ (**? ï¸<C3AF> ë°˜ë“œ????ë°©ë²• ?¬ìš© ??ì§<C3AC>ì ‘ API ?¸ì¶œ ê¸ˆì?**):
+4. 태스크 완료 처리 (반드시 이 방법 사용, 직접 API 호출 금지):
 ```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agent\workflows\vikunja_helper.py done {TASK_ID}
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py done {TASK_ID}
 ```
-   ?¬ëŸ¬ ?œìŠ¤???™ì‹œ:
+   복수 태스크 처리:
 ```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agent\workflows\vikunja_helper.py done 71 77 78
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py done 71 77 78
 ```

-5. ?œìŠ¤??ì½”ë©˜??ì¶”ê?:
+5. 태스크에 코멘트 추가:
 ```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agent\workflows\vikunja_helper.py comment {TASK_ID} "?´ìš©"
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py comment {TASK_ID} "내용"
 ```

-6. ???œìŠ¤???<3F>ì„±:
+6. 새 태스크 생성:
 ```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agent\workflows\vikunja_helper.py create "?œëª©" "?¤ëª…"
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:High
+```
+
+7. 태스크에 라벨 추가:
+```powershell
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py label {TASK_ID} Backend Priority:High
 ```

 > [!CAUTION]
-> **?ˆë?ë¡?* `Invoke-RestMethod -Method Post -Body '{"done": true}'` ê°™ì? ì§<C3AC>ì ‘ API ?¸ì¶œ???¬ìš©?˜ì? ë§ˆì„¸??
-> Vikunja API??POST ??body???¬í•¨?˜ì? ?Šì? ?„ë“œë¥?ë¹ˆê°’?¼ë¡œ ??–´?<3F>ë‹ˆ??
-> `vikunja_helper.py`????ƒ<> GET ??ê¸°ì¡´ ?„ë“œ ë³´ì¡´ ??POST ?¨í„´???¬ìš©?˜ì—¬ title/description ë³´ì¡´??ë³´ìž¥?©ë‹ˆ??
+> 절대로 Invoke-RestMethod로 직접 API를 호출하지 마세요.
+> Vikunja API는 POST 시 body에 포함되지 않은 필드를 빈값으로 덮어씁니다.
+> vikunja_helper.py는 항상 GET 후 기존 필드 보존 후 POST 패턴을 사용합니다.
--- a/.agent/workflows/debug.md
+++ b/.agent/workflows/debug.md
@@ -0,0 +1,52 @@
+---
+description: 에러/버그 발생 시 체계적 디버깅 워크플로우 (에러, 안돼요, 왜 안돼, 버그, 디버그, 수정)
+---
+
+# Debug Workflow
+
+> [!IMPORTANT]
+> 추측으로 코드를 수정하지 마세요. 반드시 이 순서를 따릅니다.
+
+## 1단계: 정보 수집 (추측 금지)
+
+- [ ] 에러 메시지 **전문** 확인 (절대 잘라내지 않기)
+- [ ] 관련 로그 파일 확인
+- [ ] 환경 정보 확인 (OS, Node/Python 버전, 의존성 버전 등)
+- [ ] 에러가 발생하는 **정확한 입력/조건** 파악
+
+## 2단계: Known Issues 확인
+
+`.agent/references/known-issues.md`를 읽고 동일하거나 유사한 문제가 있는지 확인합니다.
+
+> [!CAUTION]
+> **known-issues 확인 없이 해결 시도를 시작하지 마세요.**
+> 이미 해결된 문제를 다시 삽질하는 것은 시간 낭비입니다.
+
+## 3단계: 근본 원인 분석
+
+- [ ] 에러가 발생하는 **정확한 코드 위치** 확인
+- [ ] 가설을 세우고, 가설을 검증할 수 있는 **최소한의 테스트** 수행
+- [ ] 가설이 틀렸다면 **즉시 다른 가설로 전환**
+
+> [!WARNING]
+> **동일한 접근을 2회 초과 시도하지 마세요.**
+> 2회 실패 시 유저에게 보고하고 판단을 요청합니다.
+> 보고 내용: 시도한 것 / 실패한 것 / 원인 가설 / 다음 제안
+
+## 4단계: 수정 및 검증
+
+- [ ] 수정 적용
+- [ ] 동일 에러가 재현되지 않는지 확인
+- [ ] 사이드 이펙트(다른 기능에 영향) 없는지 확인
+
+## 5단계: 기록
+
+- [ ] `known-issues.md`에 새 항목 추가 (아래 포맷 사용)
+
+```markdown
+### [날짜] [키워드] — 한줄 요약
+- **증상**: 무엇이 잘못되었는가
+- **원인**: 근본 원인
+- **해결**: 올바른 해결 방법
+- **주의**: 재발 방지를 위한 교훈
+```
--- a/.agent/workflows/dev.md
+++ b/.agent/workflows/dev.md
@@ -1,21 +0,0 @@
---
-description: ê°œë°œ ?œë²„ ?¤í–‰ ë°©ë²•
---
-
-## ?˜ê²½ ?¤ì •
-
-1. Python ?˜ê²½ ?œì„±??
-// turbo
-```
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe -m pip install -r requirements.txt
-```
-
-2. API ?œë²„ ?¤í–‰
-```
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe -m uvicorn api.server:app --reload --host 0.0.0.0 --port 8100
-```
-
-3. Discord Bot ?¤í–‰ (ë³„ë<E2809E>„ ?°ë???
-```
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe -m api.discord_bot
-```
--- a/.agent/workflows/end.md
+++ b/.agent/workflows/end.md
@@ -0,0 +1,165 @@
+---
+description: 세션 종료 시 devlog 기록 + git commit + Vikunja 동기화 (끝, 마무리, 커밋해, 완료)
+---
+
+# 세션 종료 프로토콜
+
+작업 완료, "끝", "마무리", "커밋해" 등 요청 시 이 워크플로우를 실행합니다.
+
+// turbo-all
+
+## 0. 학습 기록 (실패/시행착오 저장)
+
+이번 세션에서 발생한 실패, 시행착오, 새로 알게 된 사실을 정리합니다:
+
+- [ ] `.agent/references/known-issues.md`에 추가할 항목이 있는지 확인
+- [ ] 있다면 아래 포맷으로 추가:
+
+```markdown
+### [날짜] [키워드] — 한줄 요약
+- **증상**: ...
+- **원인**: ...
+- **해결**: ...
+- **주의**: ...
+```
+
+## 1. Devlog 기록
+
+### Index 업데이트 (필수 — 매 작업)
+
+오늘 날짜의 index 파일에 완료된 작업 1줄을 추가합니다.
+
+- **파일**: `docs/devlog/YYYY-MM-DD.md`
+- **형식**:
+```markdown
+| NNN | HH:MM | 작업 설명 | `커밋해시` | ✅ 또는 🔧 |
+```
+
+> [!TIP]
+> - ✅ = 완료, 🔧 = 미완료 (다음 세션에서 이어받기)
+> - 파일이 없으면 새로 생성 (테이블 헤더 포함)
+
+### Entry 작성 (선택적 — 필요할 때만)
+
+> [!IMPORTANT]
+> Entry는 **git/Vikunja/wiki에 없는 정보**가 있을 때만 작성합니다.
+
+**Entry 작성 기준:**
+- ✅ 설계 결정이 있었을 때 (왜 A가 아닌 B를 선택했는지)
+- ✅ 미완료 사항이 있을 때 (다음 세션이 이어받아야 할 맥락)
+- ✅ 삽질/트러블슈팅이 있었을 때 (같은 실수 방지)
+
+**Entry 불필요:**
+- ❌ 단순 버그 픽스 (커밋 메시지로 충분)
+- ❌ 문서 업데이트 (git diff로 충분)
+- ❌ 이미 Vikunja 태스크에 상세 설명이 있는 경우
+
+**Entry 파일**: `docs/devlog/entries/YYYYMMDD-NNN.md`
+```markdown
+# 작업 제목
+
+- **시간**: YYYY-MM-DD HH:MM~HH:MM
+- **Commit**: `해시`
+- **Vikunja**: #태스크번호 → done/진행중
+
+## 결정 사항
+- 왜 이 방식을 선택했는지
+
+## 미완료
+- 남은 작업 (있을 경우)
+```
+
+---
+
+## 2. Vikunja 동기화
+
+> [!CAUTION]
+> **반드시 `vikunja_helper.py` 사용.** 직접 API 호출 금지.
+> Vikunja API는 POST 시 body에 없는 필드를 빈값으로 덮어씁니다.
+
+### 2-1. 커밋 전수 검사
+
+이번 세션의 **모든 커밋을 하나씩 검사**하고 Vikunja에 매핑합니다.
+
+```powershell
+git log --oneline -20
+```
+
+| 커밋 유형 | Vikunja 액션 |
+|-----------|-------------|
+| 기존 태스크 해당 작업 **완료** | `C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py done {ID}` |
+| 신규 작업 완료 (기존 태스크 없음) | `C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py create "제목" "설명" --done --labels Backend,Priority:High` |
+| 작업 중 발견된 **미완료 TODO** | `C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:Mid` |
+
+> [!IMPORTANT]
+> 모든 커밋이 기존 또는 신규 태스크에 매핑되었는지 확인.
+
+### 2-2. 완료 처리
+
+```powershell
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py done {TASK_ID}
+```
+
+### 2-3. 신규 태스크 생성
+
+```powershell
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:High
+```
+
+### 라벨 규칙
+
+**영역 (필수 1개 이상):** `Backend` / `Frontend` / `Engine` / `Infra` / `Test`
+**우선순위 (필수 1개):** `Priority:High` / `Priority:Mid` / `Priority:Low`
+
+---
+
+## 3. Wiki 동기화 (해당 시에만)
+
+| 코드 변경 | 대상 Wiki |
+|-----------|----------|
+| 서버 변경 | Architecture |
+| 프론트엔드 변경 | Architecture |
+| 인프라 변경 | Architecture |
+| 새 모듈/패키지 추가 | Architecture |
+
+```powershell
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\wiki_helper.py update "Architecture" /tmp/wiki_content.md
+```
+
+---
+
+## 4. Git Commit & Push
+
+```powershell
+git add -A
+git status --short
+```
+```powershell
+git commit -m "커밋 메시지"
+```
+```powershell
+git push origin main
+```
+
+**커밋 메시지 컨벤션:**
+```
+<type>(<scope>): <description>
+
+type: feat|fix|refactor|test|docs|chore|ci|infra
+scope: (선택)
+```
+
+---
+
+## 5. 최종 체크리스트
+
+> [!WARNING]
+> 아래 항목 중 하나라도 누락되면 세션 종료를 완료할 수 없습니다.
+
+- [ ] known-issues 업데이트됨 (새 이슈가 있었다면)
+- [ ] devlog index 업데이트됨
+- [ ] devlog entry 작성됨 (필요한 경우만)
+- [ ] Vikunja 태스크 생성/완료 처리됨 (커밋 전수 검사 기반)
+- [ ] Wiki 동기화됨 (아키텍처 변경이 있었다면)
+- [ ] git push 완료
+- [ ] 사용자에게 완료 보고
--- a/.agent/workflows/git.md
+++ b/.agent/workflows/git.md
@@ -1,47 +0,0 @@
---
-description: Git 및 Gitea 워크플로우
---
-
-## 저장소 정보
- **Remote**: https://git.variet.net/Variet/variet-agent.git
- **기본 브랜치**: main
- **Vikunja 프로젝트**: https://plan.variet.net/projects/7
-
-## 커밋 컨벤션
-```
-feat: 새 기능
-fix: 버그 수정
-docs: 문서 변경
-refactor: 리팩토링
-test: 테스트 추가/수정
-chore: 빌드/설정 변경
-```
-
-## 작업 흐름
-
-1. 브랜치 생성
-// turbo
-```
-git checkout -b feat/feature-name
-```
-
-2. 커밋
-// turbo
-```
-git add -A && git commit -m "feat: description"
-```
-
-3. 푸시
-```
-git push origin feat/feature-name
-```
-
-4. Gitea에서 PR 생성 또는 API로 자동 생성
-
-## Wiki 업데이트
-작업 완료 시 Gitea Wiki에 관련 내용 업데이트. 
-Wiki 구조:
- Home: 프로젝트 개요
- Architecture: 아키텍처 설명
- Design-Decisions: 설계 결정 이유
- Changelog: 버전별 변경 이력
--- a/.agent/workflows/helpers/vikunja_helper.py
+++ b/.agent/workflows/helpers/vikunja_helper.py
@@ -6,8 +6,9 @@ Usage:
  python vikunja_helper.py undone 75            # Mark task #75 as not done
  python vikunja_helper.py comment 75 "text"    # Add comment to task #75
  python vikunja_helper.py desc 75 "text"       # Set description (appends if exists)
-  python vikunja_helper.py create "title" "description"          # Create a new task
-  python vikunja_helper.py create "title" "description" --done   # Create and mark done
+  python vikunja_helper.py create "title" "desc" --labels Backend,Priority:High
+  python vikunja_helper.py create "title" "desc" --done --labels Frontend,Priority:Mid
+  python vikunja_helper.py label 75 Backend Priority:High   # Add labels to task
  python vikunja_helper.py list                 # List all tasks
  python vikunja_helper.py list todo            # List TODO only
  python vikunja_helper.py list done            # List DONE only
@@ -23,15 +24,27 @@ import io
 if sys.stdout.encoding != "utf-8":
    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")

+# ============================================================
+# ⚙️ CONFIGURATION — PROJECT_ID만 프로젝트별로 변경하세요
+# ============================================================
 API_BASE = "https://plan.variet.net/api/v1"
 TOKEN = "tk_070f8e0b715e818bb7178c3815ed5389040eddca"
-PROJECT_ID = 7
+PROJECT_ID = 7                                  # Variet Agent 프로젝트
+# ============================================================

 HEADERS = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json",
 }

+# Label name → Vikunja label ID mapping
+# Customize for your project's labels
+LABEL_MAP = {
+    "Backend": 1, "Frontend": 2, "Engine": 3, "Infra": 4, "Test": 5,
+    "Priority:High": 6, "Priority:Mid": 7, "Priority:Low": 8,
+    "Agent": 17, "Tool": 18, "AI/LLM": 19,
+}
+

 def api_get(path: str):
    req = urllib.request.Request(f"{API_BASE}{path}", headers=HEADERS)
@@ -54,12 +67,10 @@ def api_put(path: str, data: dict):


 def get_task(task_id: int) -> dict:
-    """GET full task object — preserves all fields."""
    return api_get(f"/tasks/{task_id}")


 def safe_update_task(task_id: int, updates: dict) -> dict:
-    """Safely update task: GET first, then POST with preserved fields."""
    task = get_task(task_id)
    safe_body = {
        "title": task.get("title", ""),
@@ -71,14 +82,14 @@ def safe_update_task(task_id: int, updates: dict) -> dict:
    return api_post(f"/tasks/{task_id}", safe_body)


-def mark_done(task_ids: list[int]):
+def mark_done(task_ids: list):
    for tid in task_ids:
        result = safe_update_task(tid, {"done": True})
        title = result.get("title", "?")
        print(f"  ✅ #{tid} → done=True  [{title}]")


-def mark_undone(task_ids: list[int]):
+def mark_undone(task_ids: list):
    for tid in task_ids:
        result = safe_update_task(tid, {"done": False})
        title = result.get("title", "?")
@@ -102,30 +113,60 @@ def set_description(task_id: int, desc: str, append: bool = True):


 def list_tasks(filter_: str = "all"):
-    tasks = api_get(f"/projects/{PROJECT_ID}/tasks?per_page=100")
-    if filter_ == "todo":
-        tasks = [t for t in tasks if not t["done"]]
-    elif filter_ == "done":
-        tasks = [t for t in tasks if t["done"]]
+    all_tasks = []
+    page = 1
+    while True:
+        batch = api_get(f"/projects/{PROJECT_ID}/tasks?per_page=50&page={page}")
+        if not batch:
+            break
+        all_tasks.extend(batch)
+        if len(batch) < 50:
+            break
+        page += 1

-    tasks.sort(key=lambda t: t["id"])
-    for t in tasks:
+    if filter_ == "todo":
+        all_tasks = [t for t in all_tasks if not t["done"]]
+    elif filter_ == "done":
+        all_tasks = [t for t in all_tasks if t["done"]]
+
+    all_tasks.sort(key=lambda t: t["id"])
+    for t in all_tasks:
        status = "✅" if t["done"] else "⬜"
        desc = (t.get("description") or "")[:50].replace("\n", " ")
        labels = ", ".join(l["title"] for l in (t.get("labels") or []))
        print(f"  {status} #{t['id']:3d}  {t['title'][:40]:<40}  [{labels}]  {desc}")
-    print(f"\n  Total: {len(tasks)} tasks")
+    print(f"\n  Total: {len(all_tasks)} tasks")


-def create_task(title: str, description: str = "", done: bool = False):
-    """Create a new task in the project."""
+def add_labels(task_id: int, label_names: list):
+    for name in label_names:
+        label_id = LABEL_MAP.get(name)
+        if not label_id:
+            print(f"  ⚠️ Unknown label '{name}'. Valid: {', '.join(LABEL_MAP.keys())}")
+            continue
+        try:
+            api_put(f"/tasks/{task_id}/labels", {"label_id": label_id})
+            print(f"  🏷️ #{task_id} + {name} (id={label_id})")
+        except Exception as e:
+            if "already" in str(e).lower() or "409" in str(e):
+                print(f"  🏷️ #{task_id} already has {name}")
+            else:
+                print(f"  ⚠️ #{task_id} label {name} failed: {e}")
+
+
+def create_task(title: str, description: str = "", done: bool = False, labels: list = None):
    payload = {"title": title, "description": description}
    result = api_put(f"/projects/{PROJECT_ID}/tasks", payload)
    task_id = result["id"]
    print(f"  ✨ #{task_id} created: {result.get('title', '?')}")
+
+    if labels:
+        add_labels(task_id, labels)
+
    if done:
        result = safe_update_task(task_id, {"done": True})
        print(f"  ✅ #{task_id} → done=True")
+
    return result


@@ -143,25 +184,30 @@ def main():
        ids = [int(x) for x in sys.argv[2:]]
        mark_undone(ids)
    elif cmd == "comment":
-        tid = int(sys.argv[2])
-        comment = sys.argv[3]
-        add_comment(tid, comment)
+        add_comment(int(sys.argv[2]), sys.argv[3])
    elif cmd == "desc":
-        tid = int(sys.argv[2])
-        desc = sys.argv[3]
-        set_description(tid, desc)
+        set_description(int(sys.argv[2]), sys.argv[3])
    elif cmd == "list":
        f = sys.argv[2] if len(sys.argv) > 2 else "all"
        list_tasks(f)
+    elif cmd == "label":
+        if len(sys.argv) < 4:
+            print("Usage: vikunja_helper.py label TASK_ID Label1 Label2 ...")
+            return
+        add_labels(int(sys.argv[2]), sys.argv[3:])
    elif cmd == "create":
        title = sys.argv[2] if len(sys.argv) > 2 else ""
-        desc = sys.argv[3] if len(sys.argv) > 3 else ""
+        desc = sys.argv[3] if len(sys.argv) > 3 and not sys.argv[3].startswith("--") else ""
        is_done = "--done" in sys.argv
+        labels = None
+        for i, arg in enumerate(sys.argv):
+            if arg == "--labels" and i + 1 < len(sys.argv):
+                labels = sys.argv[i + 1].split(",")
+                break
        if not title:
            print("Error: title is required")
-            print('  Usage: vikunja_helper.py create "title" "description" [--done]')
            return
-        create_task(title, desc, done=is_done)
+        create_task(title, desc, done=is_done, labels=labels)
    else:
        print(f"Unknown command: {cmd}")
        print(__doc__)
--- a/.agent/workflows/helpers/wiki_helper.py
+++ b/.agent/workflows/helpers/wiki_helper.py
@@ -0,0 +1,100 @@
+"""Gitea Wiki helper: list, read, create, update wiki pages.
+
+Usage:
+  wiki_helper.py list                     — list all pages
+  wiki_helper.py read <title>             — read a page
+  wiki_helper.py create <title> <file>    — create a page from file
+  wiki_helper.py update <title> <file>    — update a page from file
+"""
+import sys, io, json, base64, urllib.request, urllib.error
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+
+# ============================================================
+# ⚙️ CONFIGURATION — GITEA_REPO만 프로젝트별로 변경하세요
+# ============================================================
+GITEA_BASE_URL = "https://git.variet.net"
+GITEA_OWNER = "Variet"
+GITEA_REPO = "variet-agent"                       # Variet Agent 프로젝트
+GITEA_TOKEN = "3a01b4b15a39921572e64c413353e870d4d2161b"
+# ============================================================
+
+BASE = f"{GITEA_BASE_URL}/api/v1/repos/{GITEA_OWNER}/{GITEA_REPO}/wiki"
+HEADERS = {"Authorization": f"token {GITEA_TOKEN}", "Content-Type": "application/json"}
+
+def _req(method, path, data=None):
+    url = f"{BASE}{path}"
+    body = json.dumps(data).encode() if data else None
+    req = urllib.request.Request(url, data=body, headers=HEADERS, method=method)
+    try:
+        with urllib.request.urlopen(req) as resp:
+            return json.loads(resp.read().decode())
+    except urllib.error.HTTPError as e:
+        err = e.read().decode()
+        print(f"  ⚠️ HTTP {e.code}: {err}")
+        return None
+
+def _find_sub_url(title):
+    pages = _req("GET", "/pages")
+    if pages:
+        for p in pages:
+            if p.get("title", "").lower() == title.lower():
+                return p.get("sub_url", title)
+    return title
+
+def list_pages():
+    pages = _req("GET", "/pages")
+    if pages:
+        print(f"=== {len(pages)} Wiki Pages ===")
+        for p in pages:
+            print(f"  {p.get('title', '?')}")
+    return pages
+
+def read_page(title):
+    sub = _find_sub_url(title)
+    page = _req("GET", f"/page/{sub}")
+    if page and page.get("content_base64"):
+        content = base64.b64decode(page["content_base64"]).decode("utf-8")
+        return content
+    return None
+
+def create_page(title, content):
+    data = {
+        "title": title,
+        "content_base64": base64.b64encode(content.encode()).decode(),
+    }
+    result = _req("POST", "/new", data)
+    if result:
+        print(f"  ✅ Created wiki page: {title}")
+    return result
+
+def update_page(title, content):
+    sub = _find_sub_url(title)
+    data = {
+        "title": title,
+        "content_base64": base64.b64encode(content.encode()).decode(),
+    }
+    result = _req("PATCH", f"/page/{sub}", data)
+    if result:
+        print(f"  ✅ Updated wiki page: {title}")
+    return result
+
+if __name__ == "__main__":
+    cmd = sys.argv[1] if len(sys.argv) > 1 else "list"
+
+    if cmd == "list":
+        list_pages()
+    elif cmd == "read" and len(sys.argv) > 2:
+        content = read_page(sys.argv[2])
+        if content:
+            print(content[:5000])
+        else:
+            print(f"  Page '{sys.argv[2]}' not found")
+    elif cmd == "create" and len(sys.argv) > 3:
+        with open(sys.argv[3], "r", encoding="utf-8") as f:
+            create_page(sys.argv[2], f.read())
+    elif cmd == "update" and len(sys.argv) > 3:
+        with open(sys.argv[3], "r", encoding="utf-8") as f:
+            update_page(sys.argv[2], f.read())
+    else:
+        print("Usage: wiki_helper.py list|read <title>|create <title> <file>|update <title> <file>")
--- a/.agent/workflows/pre-task.md
+++ b/.agent/workflows/pre-task.md
@@ -0,0 +1,39 @@
+---
+description: 모든 구현 작업 전 실행하는 사전 점검 체크리스트 (pre-task, 준비, 시작 전, 계획, 구현)
+---
+
+# Pre-Task Checklist
+
+> [!IMPORTANT]
+> 코딩을 시작하기 전에 반드시 이 체크리스트를 순서대로 완료하세요.
+> 체크리스트를 건너뛸 경우 불필요한 시행착오가 발생합니다.
+
+## 1단계: 요구사항 정리
+
+- [ ] 유저 요청을 구체적 작업 항목으로 분해
+- [ ] 변경 범위(scope)를 명확히 정의 (영향받는 파일/모듈)
+- [ ] 성공 기준(acceptance criteria) 확인
+
+## 2단계: 레퍼런스 확인 (추측 금지)
+
+- [ ] `.agent/references/architecture.md` — 현재 아키텍처 확인
+- [ ] `.agent/references/tech-stack.md` — 기술 스택 및 버전 확인
+- [ ] `.agent/references/conventions.md` — 코딩 컨벤션 확인
+- [ ] `.agent/references/known-issues.md` — 과거 실패 패턴 확인
+- [ ] 관련 기존 코드 최소 3개 파일 읽기
+
+> [!CAUTION]
+> 레퍼런스 문서가 존재하는 주제에 대해 추측하지 마세요.
+> 문서가 없으면 유저에게 확인을 요청하세요.
+
+## 3단계: 계획 수립
+
+- [ ] 변경할 파일 목록 작성
+- [ ] 의존성 순서 파악 (어떤 파일부터 수정해야 하는가?)
+- [ ] 리스크 식별 (어디서 실패할 가능성이 높은가?)
+- [ ] 테스트 방법 결정 (어떻게 검증할 것인가?)
+
+## 4단계: 유저 확인
+
+- [ ] 계획을 유저에게 보고하고 승인받기 (변경 파일 3개 이상인 경우)
+- [ ] 작은 변경은 바로 실행하되, 변경 내용을 명확히 설명
--- a/.agent/workflows/start.md
+++ b/.agent/workflows/start.md
@@ -0,0 +1,65 @@
+---
+description: 세션 시작 시 프로젝트 맥락을 빠르게 복구하는 워크플로우 (시작, continue, 이어서, 작업 시작)
+---
+
+# 세션 시작 프로토콜
+
+새 대화 시작, "continue", "이어서", "작업 시작" 등 요청 시 이 워크플로우를 실행합니다.
+
+// turbo-all
+
+## 절차
+
+### 0. 에이전트 룰 & 맥락 로딩 (자동)
+
+`.agent/AGENT.md`를 읽고 에이전트 행동 규칙을 로딩합니다.
+`.agent/references/known-issues.md`를 읽어 최근 이슈를 파악합니다.
+
+### 1. Devlog 맥락 복구
+
+오늘 + 어제 devlog index를 읽고 최근 작업 흐름을 파악합니다.
+
+```powershell
+$today = Get-Date -Format "yyyy-MM-dd"
+$yesterday = (Get-Date).AddDays(-1).ToString("yyyy-MM-dd")
+if (Test-Path "docs\devlog\$today.md") {
+    Write-Host "=== Devlog: $today ==="
+    Get-Content "docs\devlog\$today.md"
+} elseif (Test-Path "docs\devlog\$yesterday.md") {
+    Write-Host "=== Devlog: $yesterday (no entry for today yet) ==="
+    Get-Content "docs\devlog\$yesterday.md"
+} else {
+    Write-Host "=== No recent devlog found ==="
+}
+```
+
+미완료(🔧) 항목이 있으면 해당 entry 파일을 읽어 이어받기 맥락을 확보합니다:
+- Entry 경로: `docs/devlog/entries/YYYYMMDD-NNN.md`
+
+### 2. Git 상태 확인
+
+```powershell
+git status --short
+```
+```powershell
+git log --oneline -5
+```
+
+### 3. Vikunja TODO 태스크
+
+```powershell
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py list todo
+```
+
+### 4. 종합 보고
+
+결과를 종합하여 사용자에게 보고:
+- 마지막 작업 맥락 + 미완료 항목 (devlog 🔧 기반)
+- TODO 태스크 목록 (라벨 + 우선순위)
+- 다음 작업 제안
+
+**우선순위 판단 기준** (라벨만으로 판단 금지):
+- P0: 최근 커밋에서 스키마/모델/인터페이스 변경 → 연쇄 영향 점검
+- P1: 서버 기동/API 응답 장애
+- P2: 기능 미완성/UX 개선
+- P3: 정확도 향상, 신규 기능, CI/CD, 문서 정리
--- a/.agent/workflows/sync.md
+++ b/.agent/workflows/sync.md
@@ -1,18 +0,0 @@
---
-description: 작업 동기화 및 진행 보고 절차
---
-
-## 작업 시작 시
-1. Vikunja (plan.variet.net/projects/7) 에서 해당 태스크를 "진행 중"으로 변경
-2. 관련 브랜치 생성 (feat/ 또는 fix/)
-
-## 작업 중간 동기화
-1. 의미 있는 단위로 커밋 + 푸시
-2. 필요 시 Gitea Wiki 업데이트 (Architecture, Changelog 등)
-3. 사용자에게 디스코드 또는 Vikunja 코멘트로 진행 상황 보고
-
-## 작업 완료 시
-1. Gitea PR 생성
-2. Vikunja 태스크 "완료"로 변경
-3. Changelog 업데이트
-4. Wiki 관련 페이지 업데이트
--- a/.agent/workflows/test.md
+++ b/.agent/workflows/test.md
@@ -1,24 +0,0 @@
---
-description: ?ŒìŠ¤???¤í–‰ ë°©ë²•
---
-
-## ?¨ìœ„ ?ŒìŠ¤??
-// turbo
-```
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe -m pytest tests/ -v
-```
-
-## Context Manager ?¨ê³¼ ?ŒìŠ¤??
-```
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe -m tests.test_context_manager
-```
-
-## Task Pipeline E2E
-```
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe -m tests.test_pipeline_e2e
-```
-
-## Gemini CLI ?°ë<C2B0>™ ?ŒìŠ¤??
-```
-gemini -p "Hello, respond with 'OK'" --approval-mode yolo -o json
-```