sparta-scheduler

name: sparta-scheduler description: 팀스파르타 강사 일정 관리 포털을 `ts-scheduler` CLI 로 조작합니다. "5월 둘째 주 전부 불가로 잡아줘", "5월 배정 교육 보여줘", "이번 달 계약 얼마야", "6월 1일부터 3일 간격으로 가능으로 세팅" 같은 요청에 사용하세요.

팀스파르타 강사 일정 관리 포털 (tutor-scheduler-wheat.vercel.app) 을 ts-scheduler CLI 로 조작합니다.

지원 AI CLI (이 스킬 파일 하나가 세 도구 모두에서 동작):

Claude Code — ~/.claude/skills/sparta-scheduler/
OpenCode (sst/opencode) — ~/.claude/skills/ 또는 ~/.agents/skills/ (둘 다 자동 인식)
OpenAI Codex CLI (v0.124+) — ~/.agents/skills/sparta-scheduler/ · /skills 커맨드로 노출 확인

install.sh 가 심볼릭 링크로 두 위치에 동시에 걸어두므로 세 도구 모두 추가 설정 불필요.

🚦 사용 전 프리체크 (반드시 먼저 실행)

요청을 처리하기 전에 무조건 이 한 줄로 CLI·토큰 상태를 확인하세요:

ts-scheduler auth diagnose 2>&1 || echo "__PRECHECK_FAILED__"

출력에 따라 분기:

케이스 A — CLI 가 없음 (`command not found: ts-scheduler`)

사용자에게 정확히 이 메시지 를 출력하고 대기 (에이전트가 직접 설치 금지):

sparta-scheduler 스킬을 처음 쓰시네요. CLI 설치가 필요합니다 (1회).

macOS / Linux
curl -fsSL https://raw.githubusercontent.com/seolcoding/sparta-scheduler-cli/main/install.sh | bash
Windows → README 의 PowerShell 섹션 참고: https://github.com/seolcoding/sparta-scheduler-cli#windows-powershell

설치 후 새 터미널을 여시거나 source ~/.zshrc (bash 면 ~/.bashrc) 실행해서 ts-scheduler PATH 가 잡히는지 확인해주세요. 그 다음에 다시 요청 주시면 처리하겠습니다.

케이스 B — CLI 는 있지만 토큰 없음 / 만료

diagnose 가 step 1 또는 step 4 에서 ✗ 로 실패하면:

토큰이 없거나 만료됐습니다. 터미널에서 직접 실행해주세요:
ts-scheduler auth login
브라우저 창이 열리면 Google 로그인 (@teamsparta.co 또는 등록된 강사 이메일). Google 이 막으면 ts-scheduler auth login --paste 로 재시도하면 CLI 가 상세 가이드를 출력합니다.

케이스 C — 모든 단계 ✓

사용자 요청을 해석해서 아래 커맨드 매핑대로 실행.

에이전트가 직접 실행하면 안 되는 것:

ts-scheduler auth login — 브라우저 Google 로그인이 필요
curl ... install.sh | bash — 사용자 시스템 변경은 명시적 승인 필요

커맨드 매핑 (요약)

모든 커맨드는 --json 플래그가 있습니다. 에이전트로 동작할 때는 항상 --json 을 붙여 JSON 으로 받아 파싱 후 사람이 읽기 좋은 표로 다시 렌더링하세요.

읽기 전용 (확인 없이 실행)

ts-scheduler auth whoami --json
ts-scheduler status --month YYYY-MM --json
ts-scheduler avail get --month YYYY-MM --json
ts-scheduler avail calendar --month YYYY-MM --json
ts-scheduler courses list --json
ts-scheduler courses show <course_id>
ts-scheduler profile show --json
ts-scheduler profile careers --json
ts-scheduler contracts list --json
ts-scheduler contracts list -m 2026-05 -m 2026-06 --json

쓰기 (사용자 확인 후 실행)

ts-scheduler avail set <YYYY-MM-DD> <available|unavailable|clear>
ts-scheduler avail bulk <start> <end> <status> [--step N] [--weekends|--no-weekends] [--overwrite-opposite|--keep-opposite]
ts-scheduler avail clear-month <YYYY-MM>   # 위험! 월 전체 삭제

더 자세한 옵션·에러 처리·시나리오는 같은 폴더의 reference.md 참고. 커맨드 조합 예시는 examples/ 참고.

자연어 → CLI 매핑

사용자 요청	실행 커맨드
"이번 달 요약"	`ts-scheduler status --json`
"5월 가능/불가 전체"	`ts-scheduler avail calendar --month 2026-05 --json`
"5월 전부 불가"	`ts-scheduler avail bulk 2026-05-01 2026-05-31 unavailable`
"5월 주말 빼고 전부 가능"	`ts-scheduler avail bulk 2026-05-01 2026-05-31 available --no-weekends`
"5월 셋째 주(18~24) 불가"	`ts-scheduler avail bulk 2026-05-18 2026-05-24 unavailable`
"6월 3일 간격으로 가능"	`ts-scheduler avail bulk 2026-06-01 2026-06-30 available --step 3`
"5월 일정 전부 지워줘"	`ts-scheduler avail clear-month 2026-05` (확인 필수)
"배정 교육"	`ts-scheduler courses list --json`
"내 정보"	`ts-scheduler profile show --json`
"이번 달 계약"	`ts-scheduler contracts list --json`

행동 규칙

쓰기 전 확인 — 특히 clear-month, 월 전체 bulk 는 사용자에게 "정말 실행?" 물어보고 진행.
status vs contracts 구분 — status = 가능/불가/배정 카운트, contracts list = 계약서·금액.
404/403 은 사용자 계정 권한 문제 → 그대로 사용자에게 전달.
날짜: 에이전트가 "오늘"·"이번 주"·"다음 달" 을 절대 날짜(YYYY-MM-DD, YYYY-MM) 로 변환해서 CLI 에 넘기기.
에러가 나면 stderr 의 [step N/6 …] 또는 HTTP NNN: {…} 부분을 원본 그대로 사용자에게 제시. CLI 가 이미 친절한 메시지를 낸다.
내가 설치한 스킬인지 자가 점검: 처음 호출 시 ts-scheduler version 이 0.2.0 이상인지 확인. 미만이면 bash install.sh 재실행 안내 (설치 script 자동 업데이트 지원).

sparta-scheduler