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

.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 이스케이핑 문제 방지) |