/start

name: start
description: MD 파일 또는 텍스트로 작업을 정의하면, 분석 → 디자인 확인 → 구현 → 검증 → 커밋 → PR까지 전체 플로우를 수행한다. "이거 만들어줘", "기능 구현해줘", "작업 시작하자", "이 티켓 진행해줘" 등 코드 작업 착수 발화에 사용.
category: workflow

/start — 작업 시작부터 완료까지

> **참조:** 구현 시 `rules/build-guide.md`, 완료 후 검증 시 `rules/review-guide.md`

MD 파일 또는 자유 텍스트로 작업을 정의하면, 분석 → 디자인 → 구현 → 검증 → 커밋 → PR까지 전체 플로우를 수행한다.

**[즉시 실행]** 이 메시지를 받으면 아래 흐름을 바로 실행하세요.

**작업 내용**: $ARGUMENTS

**`--auto` 모드** (슬랙봇/Channels/Remote Control 호환, 비블로킹):

• `$ARGUMENTS`에 `--auto`가 포함되면 아래 동작:
• Figma MCP 실패 시: 안내 없이 스킵
• 디자인 확인 단계: MCP 실패면 스킵
• 구현 시작 확인(8단계): LOW/MEDIUM 복잡도 → 자동 Yes / HIGH → 계획만 출력 후 중단
• AskUserQuestion 사용 최소화

**참조 규칙**:

• `@${CLAUDE_PLUGIN_ROOT}/instructions/multi-agent/coordination-guide.md` (병렬 실행)
• `@${CLAUDE_PLUGIN_ROOT}/instructions/multi-agent/agent-roster.md` (에이전트 선택)
• `@${CLAUDE_PLUGIN_ROOT}/rules/thinking-model.md` (GROUND→APPLY→VERIFY)

---

옵션

| 옵션 | 설명 | 예시 | |------|------|------| | (없음) | 전체 플로우 (분석→구현→검증→커밋→PR) | `/start feature.md` | | `--auto` | 비블로킹 모드 (슬랙봇/Channels 호환) | `/start TICKET-123 --auto` | | `--plan-only` | 분석+계획만 출력하고 멈춤 | `/start feature.md --plan-only` | | `--no-design` | 디자인 분석 스킵 | `/start "API 엔드포인트 추가" --no-design` | | `--skip-test` | 테스트 스킵 | `/start style-fix.md --skip-test` | | `--draft` | Draft PR로 생성 | `/start feature.md --draft` | | `--no-pr` | 커밋만, PR 생성 안 함 | `/start hotfix.md --no-pr` |

---

Flow CLI 자동 호출 계약 (2026-05-19 redesign G5)

`/start`는 각 Phase에서 [flow-toolkit](https://github.com/ggombee/flow-toolkit)의 `flow` CLI를 자동 호출하여 5-family 통합을 완성한다. `command -v flow` 실패 시 graceful skip (해당 Phase 본 작업은 정상 진행, flow 호출만 스킵).

| Phase | flow 명령 | 효과 | |---|---|---| | 1 (티켓 ID 감지) | `flow workflow start <ticket> --json` | `~/.flow/projects/{repo}/workflows/{id}/state.json` 생성. Codex/Cursor 이어받기 기반 | | 1-2 (BE URL 감지) | `flow spec capture <URL> --redact --json` | `.policy/api-specs/{endpoint}.md` 생성. type 정의 전 응답 우선 | | 3 (정책 매트릭스) | `flow tc select <ticket> --json` 또는 `flow policy diff <ticket>` | 영향 TC + 변경 컴포넌트 자동 식별 | | 5 (검증) | `flow run report` + `flow tc verify --stale` + `flow policy lint` | 사이클 결과 + 메타데이터 stale 검증 | | 7 (회고) | ~~`flow retro`~~ → `forge whet --draft` | 3회+ 반복 패턴 감지 → 규칙 초안 (2026-06-12 교체 — flow 휴면 의존 제거, §7-1) |

자연어 입력에 티켓 ID 패턴(`[A-Z]+-\d+`) 매칭 시 `hooks/auto-flow-trigger.sh` (UserPromptSubmit hook)가 모델 자율 의존 없이 `flow workflow start` / `flow tc select` 강제 호출.

계약: [`docs/contracts/INTEGRATION.md` §4](../../docs/contracts/INTEGRATION.md), [auto-trigger.md](../../../flow-toolkit/packages/flow-rules/docs/auto-trigger.md).

---

Phase 1: 입력 분석

1-1. 입력 판별

| 패턴 | 판별 | 처리 | |------|------|------| | `.md` 확장자 | MD 파일 | 파일 읽기 + front-matter 파싱 | | `.pen` 확장자 | Pencil 파일 | Pencil MCP로 열기 | | `figma.com/design/` URL | Figma 링크 | URL에서 fileKey/nodeId 추출 | | 그 외 | 자유 텍스트 | 그대로 요구사항으로 사용 |

1-2. MD 파일 구조 (권장)

---
title: 로그인 페이지
figma: https://figma.com/design/{fileKey}?node-id={nodeId}
pencil: design/login.pen
---

## 요구사항
- 이메일/비밀번호 로그인
- 소셜 로그인 (Google, GitHub)

## 수용 조건
- [ ] 이메일 유효성 검사
- [ ] 에러 메시지 표시

추출 정보: `title`, `figma`, `pencil`, 요구사항, 수용 조건

1-3. 프로젝트 구조 파악

ls -la
cat package.json | head -30

• 프로젝트 루트 구조
• 패키지 매니저 (lock 파일로 판단)
• 빌드/린트/테스트 명령어
• profile.json이 있으면 스택 정보 참조

---

Phase 2: 디자인 분석

> `--no-design` 옵션이거나 디자인 링크가 없으면 **이 Phase 전체를 스킵**.

2-1. 디자인 도구 감지 및 분석

**Pencil (.pen 파일 또는 Pencil URL):**

mcp__pencil__get_editor_state()      → 현재 상태
mcp__pencil__open_document(path)     → 파일 열기
mcp__pencil__batch_get(patterns)     → 노드 구조 탐색
mcp__pencil__snapshot_layout()       → 레이아웃 확인
mcp__pencil__get_screenshot()        → 시각적 확인

Pencil MCP 미연결 시: → "Pencil에서 PNG/PDF로 내보내기 후 이미지 경로를 알려주세요" 안내 → 이미지 제공 시 vision 에이전트로 분석

**Figma (URL):**

URL 파싱: https://figma.com/design/{fileKey}/?node-id={nodeId}
  → nodeId 하이픈(-)을 콜론(:)으로 변환

MCP 호출 순서:
  1. get_metadata   → 구조/스타일/컴포넌트
  2. get_screenshot → 시각적 확인 (MEDIUM 이상)
  3. get_design_context → 코드 변환 시 (HIGH)

Figma MCP 미연결 시 → REST API fallback:

if [ -z "$FIGMA_TOKEN" ]; then
  echo "Figma 분석을 위해 다음 중 하나가 필요합니다:"
  echo "  1. Figma MCP 설정 (.mcp.json)"
  echo "  2. FIGMA_TOKEN 환경변수"
  echo "  3. Figma에서 PNG 내보내기 후 경로 제공"
  exit 0
fi
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
  "https://api.figma.com/v1/images/${FILE_KEY}?ids=${NODE_ID}&format=png&scale=2"
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
  "https://api.figma.com/v1/files/${FILE_KEY}/nodes?ids=${NODE_ID}&depth=5"

**이미지 파일 (PNG/JPG/PDF):**

Task(subagent_type = 'vision', model = 'sonnet',
  prompt = '이 디자인 이미지를 분석: 레이아웃, 컴포넌트, 색상, 간격, 상태별 스타일');

2-2. 복잡도별 분석 깊이

| 복잡도 | 디자인 분석 범위 | MCP 호출 | |--------|-----------------|----------| | LOW (1파일, 스타일 변경) | 스크린샷만 확인 | get_screenshot | | MEDIUM (2-5파일) | 구조 + 스크린샷 | get_metadata → get_screenshot | | HIGH (5+파일, 새 화면) | 전체 분석 | get_metadata → get_screenshot → get_design_context |

2-3. 디자인 분석 체크리스트

• [ ] 전체 레이아웃 (flex/grid, gap, padding)
• [ ] 주요 컴포넌트 목록
• [ ] 색상 팔레트 (semantic color / hex)
• [ ] 타이포그래피 (size, weight, line-height)
• [ ] 상태별 스타일 (기본/hover/active/disabled/selected)
• [ ] 반응형 동작 (있는 경우)

---

Phase 3: 코드 분석 + 계획

3-1. 병렬 코드 탐색 (복잡도 조건부 — 2026-06-12 §4-6 사용자 결정)

명백한 LOW(1개 파일, 스타일/텍스트 변경이 요구사항에서 자명)는 **scout 생략**하고 대상 파일 직접 Read. 그 외에는 scout 병렬:

Task(subagent_type = 'scout', model = 'haiku', prompt = '변경 대상 영역 구조 분석');
Task(subagent_type = 'scout', model = 'haiku', prompt = '기존 패턴 및 컨벤션 분석');
Task(subagent_type = 'scout', model = 'haiku', prompt = '관련 유틸/서비스/훅 파악');

HIGH(§3-3)면 Plan 에이전트가 **필수** — 스폰 생략 금지. (LOW 생략/MEDIUM+ 병렬/HIGH 필수 — 비용은 복잡도에 비례하게)

3-2. 디자인 vs 코드 비교 (디자인 분석이 있을 때)

| 항목 | 디자인 | 코드 | 일치 | |------|--------|------|:----:| | {항목} | {값} | {값} | O/X |

**불일치 = 반드시 작업 내용에 포함**

3-3. 복잡도 판단

| 복잡도 | 기준 | 전략 | |--------|------|------| | **LOW** | 1개 파일, 스타일/텍스트 변경 | 바로 구현 | | **MEDIUM** | 2-5개 파일, 기존 패턴 | 패턴 확인 후 구현 | | **HIGH** | 5개+ 파일, 새 아키텍처 | Plan