Avishai-Tsabari/mercury-skills

트래커 — 움직이는 작업을 추적합니다

이 스킬이 적합한 경우

시그니처 질문: "이것의 상태가 어떻게 되나요?" 또는 "누가 이것을 담당하나요?"

트래커 = 상태 간을 이동하고, 담당자와 타임라인이 있으며, 기록을 보존할 가치가 있는 항목들입니다.

라우팅 테스트

트래커를 사용하려면 다음 중 최소 두 가지가 필요합니다:

• 시간에 따라 변하는 상태 (속성이 아닌 이동)
• 사람 담당자
• 마감일
• 계층 구조: 그룹 → 하위 그룹 → 항목

두 가지 미만인 경우 → registry. ⚠️ 기본값은 항상 레지스트리입니다.

구축 방법

하나의 엔진, 여러 스키마.

<tracker-dir>/
  schema.json    상태, 우선순위, 계층 레이블, 추가 필드
  tracker.db     SQLite: 항목 + 그룹 + item_history

엔진: engine/tracker.py (이 SKILL.md 옆에 위치) · Python 3.9+ · 의존성 없음 (내장 sqlite3 사용).

계층 구조: group → subgroup → item. 레이블은 도메인에 따라 변경됩니다 — 작업의 경우 프로젝트 → 모듈 → 작업, 버그의 경우 제품 → 구성 요소 → 버그, 인보이스의 경우 클라이언트 → 구독 → 인보이스입니다.

사용자와 함께 작업하기

1. 라우팅 테스트를 실행합니다. 평평한 목록인 경우 → registry.
2. 스키마를 제안합니다: 어떤 상태, 무엇이 "종료됨"으로 간주되는지, 어떤 우선순위, 계층 구조가 무엇인지, 어떤 추가 필드가 있는지. 제시하고 승인을 요청합니다.
3. presets/에서 사전 설정이 있는지 확인합니다.
4. init으로 생성하고 그룹을 추가한 다음, 워크스페이스 수준의 registries.json 인덱스에 트래커를 등록합니다.
5. 업데이트는 자연어로 보고할 수 있으며 — 에이전트가 이를 명령어로 변환한다고 설명합니다.

명령어

경로는 워크스페이스 루트를 기준으로 합니다. SKILL_DIR을 이 스킬이 설치된 위치(예: .pi/skills/tracker)로 조정하세요.

T=<SKILL_DIR>/engine/tracker.py
D=trackers/bugs

python3 $T --dir $D init --preset bugs
python3 $T --dir $D group add webapp --name "Web App"
python3 $T --dir $D group add checkout --name "Checkout" --parent webapp
python3 $T --dir $D add "Double booking in calendar" --group webapp --subgroup checkout \
        --assignee dana --priority sev2 --client acme --due 2026-08-05
python3 $T --dir $D update 3 --status in-progress --notes "reproduced"
python3 $T --dir $D list --assignee dana --group-by status
python3 $T --dir $D list --status blocked
python3 $T --dir $D show 3
python3 $T --dir $D history 3
python3 $T --dir $D report          # 요약: 상태별, 담당자별, 기한 초과, 차단됨
python3 $T --dir $D delete 3 --yes  # ⚠️ 영구 삭제

list는 필터 없이 실행하면 자동으로 종료된 항목을 숨깁니다. --all은 모든 항목을 표시합니다.

사용 가능한 사전 설정

tasks 작업 · bugs 버그 및 클라이언트 문제 · invoices 인보이스 및 수금 · features 기능 파이프라인

사전 설정 해결 순서

init --preset <이름>은 다음 순서로 <이름>.json을 찾습니다 — 첫 번째 일치 항목이 사용됩니다:

1. <workspace>/trackers/presets/<이름>.json — 워크스페이스 로컬 사전 설정, 엔진이 실행되는 작업 디렉토리를 기준으로 함
2. <SKILL_DIR>/presets/<이름>.json — 위에 나열된 내장 사전 설정

동일한 이름의 워크스페이스 로컬 사전 설정은 내장 사전 설정을 덮어씁니다. 사전 설정이 없으면 두 위치의 모든 사용 가능한 이름이 [space] / [built-in] 태그와 함께 나열됩니다.

워크스페이스 로컬 사전 설정 작성: schema.json과 동일한 형식의 스키마 JSON(내장 사전 설정 예시 참조)을 trackers/presets/에 넣습니다. 이 디렉토리는 명시적인 --preset <이름>이 있을 때만 읽히며 — 다른 파일은 무시됩니다.

철칙

• 📊 트래커가 진실의 원천입니다 — 에이전트의 메모리에 상태를 절대 유지하지 마세요. 항상 쿼리하세요.
• ⛔ blocked 상태에는 노트에 이유가 있어야 합니다 — 그렇지 않으면 차단이 의미가 없습니다.
• 🗑️ 삭제는 --yes와 명시적인 사용자 확인이 필요합니다. 기본적으로 "취소됨" 상태는 없습니다 — 필요하다면 삭제 대신 스키마에 추가하세요.
• 📜 모든 변경 사항은 item_history에 기록됩니다 — 절대 DB를 직접 편집하지 마세요.
• 🔁 상태가 세 개 이하이고 담당자와 마감일이 없으면 = 레지스트리여야 했습니다.