refactor: sync .agents/ with agent_guide template (helpers/ subdir, devlog, pre-task, debug, references)

.agents/AGENT.md

@@ -0,0 +1,51 @@
+---
+description: 모든 작업에 자동 적용되는 에이전트 행동 규칙. 새 대화 시작 시 반드시 이 파일을 먼저 읽습니다.
+---
+
+# Agent Rules — Gravity Web
+
+## Identity
+
+당신은 Gravity Web 프로젝트의 시니어 개발자입니다. 지시를 정확히 따르고, 추측보다 근거를 우선합니다.
+
+## NEVER (절대 금지)
+
+1. NEVER start coding without reading relevant reference documents in `.agents/references/`
+2. NEVER guess when documentation exists — always check `.agents/references/` first
+3. NEVER repeat a failed approach — check `.agents/references/known-issues.md` first
+4. NEVER call Vikunja/Gitea API directly — use `vikunja_helper.py` / `wiki_helper.py`
+5. NEVER skip the pre-task checklist defined in `.agents/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
+8. NEVER use `curl` in PowerShell — always use `curl.exe`
+9. NEVER run `npm` directly — use `cmd /c npm` to avoid execution policy issues
+
+## ALWAYS (필수)
+
+1. ALWAYS run `.agents/workflows/pre-task.md` before any implementation task
+2. ALWAYS check `.agents/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 `vikunja_helper.py` for Vikunja operations (GET→preserve→POST pattern)
+6. ALWAYS use `wiki_helper.py` for Gitea Wiki operations
+7. 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. `.agents/AGENT.md` (this file — behavior rules)
+2. `.agents/references/known-issues.md` (past failure patterns)
+3. `.agents/references/` (project-specific knowledge)
+4. `.agents/workflows/services.md` (service credentials & URLs)
+5. `.agents/workflows/` (action procedures)

.agents/references/architecture.md

@@ -0,0 +1,57 @@
+# Architecture — Gravity Web
+
+> AI 에이전트는 구현 전 이 문서를 반드시 확인합니다.
+
+## 프로젝트 개요
+
+Antigravity IDE(Google의 AI-powered IDE) 여러 인스턴스를 웹 브라우저에서 원격으로 연결하여 세션을 전환하며 채팅/명령을 주고받는 대시보드.
+
+## 아키텍처
+
+```
+┌─────────────────┐     HTTP/WS      ┌──────────────────┐    CDP     ┌──────────────┐
+│  웹 브라우저     │ ◄──────────────► │ Gravity Web      │ ◄───────► │ Antigravity  │
+│  (Dashboard)    │   :3300          │ Server (Node.js) │  :9000    │ IDE #1       │
+└─────────────────┘                  │                  │  :9001    │ IDE #2       │
+                                     └──────────────────┘           └──────────────┘
+```
+
+## 디렉토리 구조
+
+```
+gravity_web/
+├── server/
+│   ├── package.json           # 의존성
+│   ├── index.js               # Express + WebSocket 서버
+│   ├── cdp-client.js          # CDP 연결/스크래핑/입력
+│   └── session-manager.js     # 다중 세션 관리
+├── public/
+│   ├── index.html             # SPA 대시보드
+│   ├── css/style.css          # 다크 테마
+│   └── js/
+│       ├── app.js             # WebSocket + 이벤트 라우팅
+│       ├── session-panel.js   # 세션 목록 UI
+│       └── chat-panel.js      # 채팅 UI
+├── extension/                 # Extension Bridge (승인/거절 기능)
+├── .agents/                   # AI 에이전트 설정
+└── docs/                      # 문서
+```
+
+## 핵심 모듈
+
+| 모듈 | 파일 | 역할 |
+|------|------|------|
+| Express 서버 | `server/index.js` | HTTP + WebSocket 서버 (port 3300) |
+| CDP 클라이언트 | `server/cdp-client.js` | Chrome DevTools Protocol로 Antigravity 연결 |
+| 세션 매니저 | `server/session-manager.js` | 다중 Antigravity 인스턴스 관리 |
+| 앱 컨트롤러 | `public/js/app.js` | WebSocket + 이벤트 라우팅 |
+| 세션 패널 | `public/js/session-panel.js` | 세션 목록 UI |
+| 채팅 패널 | `public/js/chat-panel.js` | 채팅 인터페이스 |
+
+## CDP (Chrome DevTools Protocol) 동작 원리
+
+1. Antigravity.exe를 `--remote-debugging-port=9000`으로 실행
+2. 서버가 CDP 포트에 연결
+3. DOM 스크래핑 (1초 간격 폴링)
+4. `Runtime.evaluate` + `Input.dispatchKeyEvent`로 메시지 전송
+5. `Page.captureScreenshot`으로 미리보기

.agents/references/conventions.md

@@ -0,0 +1,38 @@
+# Coding Conventions — Gravity Web
+
+> AI 에이전트는 코드를 작성하기 전 이 컨벤션을 확인합니다.
+
+## 네이밍
+
+| 대상 | 규칙 | 예시 |
+|------|------|------|
+| 변수/함수 | camelCase | `getUserData()` |
+| 클래스 | PascalCase | `SessionManager` |
+| 상수 | UPPER_SNAKE_CASE | `CDP_POLL_INTERVAL` |
+| 파일명 | kebab-case | `cdp-client.js`, `session-panel.js` |
+| CSS 클래스 | kebab-case | `.session-card`, `.chat-bubble` |
+
+## 커밋 메시지
+
+```
+<type>(<scope>): <description>
+
+type: feat|fix|refactor|test|docs|chore|ci|infra
+scope: server|frontend|cdp|infra (선택)
+```
+
+**예시:**
+- `feat(server): add WebSocket reconnection logic`
+- `fix(cdp): handle disconnection timeout`
+- `docs: update Architecture wiki`
+
+## Vikunja 태깅 규칙
+
+- **영역 라벨 (필수, 1개 이상):** `Backend` / `Frontend` / `Infra` / `Test`
+- **우선순위 라벨 (필수, 1개):** `Priority:High` / `Priority:Mid` / `Priority:Low`
+
+## 주석
+
+- 한국어/영어 혼용 가능
+- TODO 주석: `// TODO: 설명`
+- 복잡한 로직: WHY(왜) 주석 필수

.agents/references/known-issues.md

@@ -0,0 +1,49 @@
+# Known Issues & Lessons Learned — Gravity Web
+
+> **이 파일은 SSOT(Single Source of Truth)입니다.**
+> 디버깅이나 구현 전에 **반드시** 이 파일을 확인하세요.
+> 세션 종료 시 새로 발견된 이슈를 이 파일에 추가합니다.
+
+---
+
+## 공통 이슈
+
+### [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] Vikunja API — POST 시 필드 덮어씌움
+- **증상**: 태스크 업데이트 시 기존 라벨/설명이 사라짐
+- **원인**: Vikunja API POST 시 body에 없는 필드를 빈값으로 덮어씀
+- **해결**: `vikunja_helper.py` 사용 (GET → 기존 필드 보존 → POST 패턴)
+- **주의**: **절대로** `Invoke-RestMethod -Method Post -Body '{\"done\": true}'` 같은 직접 API 호출 금지
+
+### [2026-03-08] PowerShell JSON 파이프 — 이스케이핑 문제
+- **증상**: PowerShell에서 JSON을 파이프로 전달할 때 따옴표/특수문자가 깨짐
+- **원인**: PowerShell의 이스케이핑 규칙이 bash와 다름
+- **해결**: JSON 처리가 필요하면 `.py` 스크립트로 만들어 실행
+- **주의**: 복잡한 API 호출은 반드시 Python 헬퍼 스크립트 사용
+
+---
+
+## CDP 관련 이슈
+
+### [2026-03-08] CDP 연결 — Antigravity.exe 직접 실행 필수
+- **증상**: `antigravity .` CLI로 실행 시 CDP 포트가 열리지 않음
+- **원인**: CLI 래퍼가 `ELECTRON_RUN_AS_NODE=1`을 설정하여 CDP 비활성화
+- **해결**: `"%LOCALAPPDATA%\Programs\Antigravity\Antigravity.exe" --remote-debugging-port=9000`으로 직접 실행
+- **주의**: 기존 Antigravity 프로세스가 있으면 새 인스턴스가 합류하여 별도 CDP 포트 열리지 않음. 모든 인스턴스 종료 후 실행
+
+---
+
+## 프로젝트별 이슈
+
+(세션 진행 중 발견되는 이슈를 여기에 추가)

.agents/references/tech-stack.md

@@ -0,0 +1,42 @@
+# Tech Stack — Gravity Web
+
+> AI 에이전트는 구현 전 이 문서를 확인하여 올바른 기술/버전을 사용합니다.
+
+## 언어 & 런타임
+
+| 항목 | 버전 | 비고 |
+|------|------|------|
+| Node.js | 시스템 설치 (`node`, `npm`) | 서버 + 빌드 |
+| Python | `C:\ProgramData\miniforge3\envs\gravity_web\python.exe` | 헬퍼 스크립트 전용 |
+
+## 프레임워크 & 라이브러리
+
+| 항목 | 용도 |
+|------|------|
+| Express | HTTP 서버 |
+| ws | WebSocket 서버 |
+| chrome-remote-interface | CDP 클라이언트 |
+
+## 프론트엔드
+
+| 항목 | 설명 |
+|------|------|
+| 방식 | Vanilla HTML/CSS/JS (SPA) — 프레임워크 없음 |
+| 테마 | 다크 테마 |
+| 통신 | REST API + WebSocket (실시간) |
+
+## 개발 도구
+
+| 도구 | 명령어 |
+|------|--------|
+| 의존성 설치 | `cmd /c npm install` (server 디렉토리에서) |
+| 서버 실행 | `cmd /c node index.js` (server 디렉토리에서, port 3300) |
+| Antigravity 실행 | `"%LOCALAPPDATA%\Programs\Antigravity\Antigravity.exe" --remote-debugging-port=9000` |
+
+## Shell 주의사항
+
+| 항목 | 규칙 |
+|------|------|
+| `curl` | PowerShell에서 `Invoke-WebRequest` 별칭 → **반드시 `curl.exe`** |
+| `npm` | 실행 정책 문제 시 **`cmd /c npm`** 사용 |
+| JSON 처리 | `.py` 스크립트로 만들어 실행 (PowerShell 이스케이핑 문제 방지) |

.agents/workflows/check-gitea.md

@@ -26,15 +26,15 @@ $issues | ForEach-Object { Write-Host "#$($_.number) $($_.title)" }
 
 3. Wiki 페이지 목록:
 ```powershell
-python .agents\workflows\wiki_helper.py list
+python .agents\workflows\helpers\wiki_helper.py list
 ```
 
 4. Wiki 페이지 읽기:
 ```powershell
-python .agents\workflows\wiki_helper.py read "Architecture"
+python .agents\workflows\helpers\wiki_helper.py read "Architecture"
 ```
 
 5. Wiki 페이지 업데이트:
 ```powershell
-python .agents\workflows\wiki_helper.py update "페이지-제목" /tmp/wiki_content.md
+python .agents\workflows\helpers\wiki_helper.py update "페이지-제목" /tmp/wiki_content.md
 ```

.agents/workflows/check-vikunja.md

@@ -12,27 +12,27 @@ description: Vikunja API로 gravity_web 프로젝트 태스크 현황을 조회
 
 1. 전체 목록:
 ```powershell
-python .agents\workflows\vikunja_helper.py list
+python .agents\workflows\helpers\vikunja_helper.py list
 ```
 
 2. TODO만:
 ```powershell
-python .agents\workflows\vikunja_helper.py list todo
+python .agents\workflows\helpers\vikunja_helper.py list todo
 ```
 
 3. DONE만:
 ```powershell
-python .agents\workflows\vikunja_helper.py list done
+python .agents\workflows\helpers\vikunja_helper.py list done
 ```
 
 4. 태스크 완료 처리 (**⚠️ 반드시 이 방법 사용 — 직접 API 호출 금지**):
 ```powershell
-python .agents\workflows\vikunja_helper.py done {TASK_ID}
+python .agents\workflows\helpers\vikunja_helper.py done {TASK_ID}
 ```
 
 5. 새 태스크 생성:
 ```powershell
-python .agents\workflows\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:High
+python .agents\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:High
 ```
 
 > [!CAUTION]

.agents/workflows/debug.md

@@ -0,0 +1,50 @@
+---
+description: 에러/버그 발생 시 체계적 디버깅 워크플로우 (에러, 안돼요, 왜 안돼, 버그, 디버그, 수정)
+---
+
+# Debug Workflow
+
+> [!IMPORTANT]
+> 추측으로 코드를 수정하지 마세요. 반드시 이 순서를 따릅니다.
+
+## 1단계: 정보 수집 (추측 금지)
+
+- [ ] 에러 메시지 **전문** 확인 (절대 잘라내지 않기)
+- [ ] 관련 로그 파일 확인
+- [ ] 환경 정보 확인 (OS, Node 버전 등)
+- [ ] 에러가 발생하는 **정확한 입력/조건** 파악
+
+## 2단계: Known Issues 확인
+
+`.agents/references/known-issues.md`를 읽고 동일하거나 유사한 문제가 있는지 확인합니다.
+
+> [!CAUTION]
+> **known-issues 확인 없이 해결 시도를 시작하지 마세요.**
+
+## 3단계: 근본 원인 분석
+
+- [ ] 에러가 발생하는 **정확한 코드 위치** 확인
+- [ ] 가설을 세우고, 가설을 검증할 수 있는 **최소한의 테스트** 수행
+- [ ] 가설이 틀렸다면 **즉시 다른 가설로 전환**
+
+> [!WARNING]
+> **동일한 접근을 2회 초과 시도하지 마세요.**
+> 2회 실패 시 유저에게 보고: 시도한 것 / 실패한 것 / 원인 가설 / 다음 제안
+
+## 4단계: 수정 및 검증
+
+- [ ] 수정 적용
+- [ ] 동일 에러가 재현되지 않는지 확인
+- [ ] 사이드 이펙트(다른 기능에 영향) 없는지 확인
+
+## 5단계: 기록
+
+- [ ] `known-issues.md`에 새 항목 추가:
+
+```markdown
+### [날짜] [키워드] — 한줄 요약
+- **증상**: 무엇이 잘못되었는가
+- **원인**: 근본 원인
+- **해결**: 올바른 해결 방법
+- **주의**: 재발 방지를 위한 교훈
+```

.agents/workflows/end.md

@@ -1,5 +1,5 @@
 ---
-description: 세션 종료 시 git commit + Vikunja 동기화
+description: 세션 종료 시 devlog 기록 + git commit + Vikunja 동기화 (끝, 마무리, 커밋해, 완료)
 ---
 
 # 세션 종료 프로토콜
@@ -8,14 +8,74 @@ description: 세션 종료 시 git commit + Vikunja 동기화
 
 // turbo-all
 
-## 1. Vikunja 동기화
+## 0. 학습 기록 (실패/시행착오 저장)
+
+이번 세션에서 발생한 실패, 시행착오, 새로 알게 된 사실을 정리합니다:
+
+- [ ] `.agents/references/known-issues.md`에 추가할 항목이 있는지 확인
+- [ ] 있다면 아래 포맷으로 추가:
+
+```markdown
+### [날짜] [키워드] — 한줄 요약
+- **증상**: ...
+- **원인**: ...
+- **해결**: ...
+- **주의**: ...
+```
+
+## 1. Devlog 기록
+
+### Index 업데이트 (필수 — 매 작업)
+
+오늘 날짜의 index 파일에 완료된 작업 1줄을 추가합니다.
+
+- **파일**: `docs/devlog/YYYY-MM-DD.md`
+- **형식**:
+```markdown
+| NNN | HH:MM | 작업 설명 | `커밋해시` | ✅ 또는 🔧 |
+```
+
+### 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에 없는 필드를 빈값으로 덮어씁니다.
 
-### 1-1. 커밋 전수 검사
+### 2-1. 커밋 전수 검사
 
-이번 세션의 모든 커밋을 확인하고 Vikunja에 매핑:
+이번 세션의 **모든 커밋을 하나씩 검사**하고 Vikunja에 매핑합니다.
 
 ```powershell
 git log --oneline -20
@@ -23,11 +83,14 @@ git log --oneline -20
 
 | 커밋 유형 | Vikunja 액션 |
 |-----------|-------------|
-| 기존 태스크 해당 작업 완료 | `python .agents\workflows\vikunja_helper.py done {ID}` |
+| 기존 태스크 해당 작업 **완료** | `python .agents\workflows\helpers\vikunja_helper.py done {ID}` |
-| 신규 작업 완료 (기존 태스크 없음) | `python .agents\workflows\vikunja_helper.py create "제목" "설명" --done --labels Backend,Priority:High` |
+| 신규 작업 완료 (기존 태스크 없음) | `python .agents\workflows\helpers\vikunja_helper.py create "제목" "설명" --done --labels Backend,Priority:High` |
-| 작업 중 발견된 미완료 TODO | `python .agents\workflows\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:Mid` |
+| 작업 중 발견된 **미완료 TODO** | `python .agents\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:Mid` |
 
-### 1-2. Wiki 동기화 (해당 시에만)
+> [!IMPORTANT]
+> 모든 커밋이 기존 또는 신규 태스크에 매핑되었는지 확인.
+
+### 2-2. Wiki 동기화 (해당 시에만)
 
 | 코드 변경 | 대상 Wiki |
 |-----------|----------|
@@ -36,10 +99,12 @@ git log --oneline -20
 | 프론트엔드 변경 | Architecture |
 
 ```powershell
-python .agents\workflows\wiki_helper.py update "Architecture" /tmp/wiki_content.md
+python .agents\workflows\helpers\wiki_helper.py update "Architecture" /tmp/wiki_content.md
 ```
 
-## 2. Git Commit & Push
+---
+
+## 3. Git Commit & Push
 
 ```powershell
 git add -A
@@ -60,9 +125,17 @@ type: feat|fix|refactor|test|docs|chore|ci|infra
 scope: server|frontend|cdp|infra (선택)
 ```
 
-## 3. 최종 체크리스트
+---
 
-- [ ] Vikunja 태스크 생성/완료 처리됨
+## 4. 최종 체크리스트
+
+> [!WARNING]
+> 아래 항목 중 하나라도 누락되면 세션 종료를 완료할 수 없습니다.
+
+- [ ] known-issues 업데이트됨 (새 이슈가 있었다면)
+- [ ] devlog index 업데이트됨
+- [ ] devlog entry 작성됨 (필요한 경우만)
+- [ ] Vikunja 태스크 생성/완료 처리됨 (커밋 전수 검사 기반)
 - [ ] Wiki 동기화됨 (해당 시)
 - [ ] git push 완료
 - [ ] 사용자에게 완료 보고

.agents/workflows/pre-task.md

@@ -0,0 +1,38 @@
+---
+description: 모든 구현 작업 전 실행하는 사전 점검 체크리스트 (pre-task, 준비, 시작 전, 계획, 구현)
+---
+
+# Pre-Task Checklist
+
+> [!IMPORTANT]
+> 코딩을 시작하기 전에 반드시 이 체크리스트를 순서대로 완료하세요.
+
+## 1단계: 요구사항 정리
+
+- [ ] 유저 요청을 구체적 작업 항목으로 분해
+- [ ] 변경 범위(scope)를 명확히 정의 (영향받는 파일/모듈)
+- [ ] 성공 기준(acceptance criteria) 확인
+
+## 2단계: 레퍼런스 확인 (추측 금지)
+
+- [ ] `.agents/references/architecture.md` — 현재 아키텍처 확인
+- [ ] `.agents/references/tech-stack.md` — 기술 스택 및 버전 확인
+- [ ] `.agents/references/conventions.md` — 코딩 컨벤션 확인
+- [ ] `.agents/references/known-issues.md` — 과거 실패 패턴 확인
+- [ ] 관련 기존 코드 최소 3개 파일 읽기
+
+> [!CAUTION]
+> 레퍼런스 문서가 존재하는 주제에 대해 추측하지 마세요.
+> 문서가 없으면 유저에게 확인을 요청하세요.
+
+## 3단계: 계획 수립
+
+- [ ] 변경할 파일 목록 작성
+- [ ] 의존성 순서 파악 (어떤 파일부터 수정해야 하는가?)
+- [ ] 리스크 식별 (어디서 실패할 가능성이 높은가?)
+- [ ] 테스트 방법 결정 (어떻게 검증할 것인가?)
+
+## 4단계: 유저 확인
+
+- [ ] 계획을 유저에게 보고하고 승인받기 (변경 파일 3개 이상인 경우)
+- [ ] 작은 변경은 바로 실행하되, 변경 내용을 명확히 설명

.agents/workflows/services.md

@@ -43,7 +43,7 @@ description: Gravity Web 프로젝트 연동 서비스 URL, API 키, 프로젝
 > 태스크 목록은 항상 라이브 조회를 사용합니다. 하드코딩된 매핑은 유지하지 않습니다.
 
 ```powershell
-python .agents\workflows\vikunja_helper.py list todo
+python .agents\workflows\helpers\vikunja_helper.py list todo
 ```
 
 ## 기타 서비스

.agents/workflows/start.md

@@ -1,5 +1,5 @@
 ---
-description: 세션 시작 시 프로젝트 맥락을 빠르게 복구하는 워크플로우
+description: 세션 시작 시 프로젝트 맥락을 빠르게 복구하는 워크플로우 (시작, continue, 이어서, 작업 시작)
 ---
 
 # 세션 시작 프로토콜
@@ -10,7 +10,33 @@ description: 세션 시작 시 프로젝트 맥락을 빠르게 복구하는 워
 
 ## 절차
 
-### 1. Git 상태 확인
+### 0. 에이전트 룰 & 맥락 로딩 (자동)
+
+`.agents/AGENT.md`를 읽고 에이전트 행동 규칙을 로딩합니다.
+`.agents/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
@@ -19,27 +45,21 @@ git status --short
 git log --oneline -5
 ```
 
-### 2. Vikunja TODO 태스크
+### 3. Vikunja TODO 태스크
 
 ```powershell
-python .agents\workflows\vikunja_helper.py list todo
+python .agents\workflows\helpers\vikunja_helper.py list todo
-```
-
-### 3. Wiki 아키텍처 확인 (필요 시)
-
-```powershell
-python .agents\workflows\wiki_helper.py read "Architecture"
 ```
 
 ### 4. 종합 보고
 
 결과를 종합하여 사용자에게 보고:
-- 마지막 커밋 + 미완료 태스크
+- 마지막 작업 맥락 + 미완료 항목 (devlog 🔧 기반)
 - TODO 태스크 목록 (라벨 + 우선순위)
 - 다음 작업 제안
 
-**우선순위 판단 기준:**
+**우선순위 판단 기준** (라벨만으로 판단 금지):
-- P0: CDP 연결 관련 (Antigravity 연결이 안되면 전체 기능 불가)
+- P0: 핵심 기능 연결 관련 (전체 기능 불가)
-- P1: 서버/WebSocket 통신 장애
+- P1: 서버/통신 장애
 - P2: 기능 미완성/UX 개선
 - P3: 문서, 코드 정리